What is a software specification and why not underestimate it

The software specification is one of the most important documents in software development. Yet it is a term that is often interpreted differently by companies - sometimes simplistically as a "list of requirements", sometimes as a "client brief". But the reality is much broader and deeper. A well-crafted software specification can protect both sides of a collaboration and significantly reduce the risk of a project hitting a time slip, budget or misunderstanding.

In this article, we explain in detail what a software specification is and what it is not, what it contains, why it is important and who it helps, and how we work with it at TRITON IT.

What is a software specification?

A software specification is a detailed document that describes what is to be created, how it is to work, under what conditions the result will be considered finished and what risks need to be taken into account. It is not just a "wish list" or a brief written on paper. It is a formal agreement between the client and the supplier, setting out specific requirements and expectations - mutually agreed.

The creation of a specification is usually the subject of a separate pricing, because only on this basis can the price of the project be reliably determined - assuming it is to be determined in advance and is final. In the case of agile development methodologies, the total price may vary depending on the development stages. Therefore, the specification often includes a detailed description of the work and its architecture in the form of text or, for example, UML diagrams.

What is UML?

UML (Unified Modeling Language) is a standardized language for visual modeling of software systems. It is used to capture the structure, behaviour and architecture of a system using diagrams that facilitate design, analysis and communication between developers. UML helps to translate ideas into understandable models.

What is PlantUML?

PlantUML is a descriptive language that allows UML diagrams to be defined in a textual and standardized way. While UML itself is just a graphical notation, PlantUML provides a way to create these diagrams using simple code. This allows for easy integration into versioning systems, automation of documentation, and also the generation of diagrams using AI, such as large language models (LLMs). This allows software architects to more efficiently design AI-enabled system architectures.

The specification aims to remove ambiguity. The moment development begins without a precise specification, assumption, interpretation and room for error set in. A good specification sets the rules of the game - for development, testing and handover.

What does a software specification contain?

A software specification is a precise and detailed guide to what the result should look like. Think of it as a detailed building plan for a house - when you want a house, it's not enough to say "I want a house with three bedrooms and a bathroom". The architect has to give you a plan that shows exactly what will go where, what materials will be used, where the lights will be, electricity, where the doors are, how thick the walls are, etc. It's the same with software.

1. Description of the work

This is where you simply describe what is going to be created. Whether it's a web app, an internal company system, a mobile app, or perhaps a filing tool. The goal is to make sure that both parties have the same idea of what the outcome of the project is.

Example

2. Functional requirements

Functional requirements are a list of specific functions that the software should be able to do. What the user will be able to do - e.g. log in, search for an item, edit a profile, download an invoice. And the important thing - part of the specification includes things that the application will not be able to do, even though they may seem obvious.

Example:

• A user can log in with an email and password.
  
• The app will not allow registration using a Facebook or Google account.
  
• The administrator can delete user accounts.

3. Non-functional requests

These are not feature requirements, but rather conditions and constraints under which the system should operate. These include, for example, how fast the system is supposed to respond, what device it is supposed to run on, what the expected load on the system is, what technologies are to be used, or what data it is supposed to handle.

Example:

• The system will be optimised for mobile phones.
  
• It will run on a client server running Linux.
  
• It must be compatible with Chrome and Firefox browsers.
  
• It must be able to handle 500 concurrently connected users.
  

4. Procedures leading to the goal

This describes how the development will proceed. What steps will be followed in sequence, what milestones are set, how often reports will be sent, when to test what, when to hand over what.

Example:

• Phase one: user interface design.
  
• Phase two: development of core functionality.
  
• Phase three: testing and debugging.
  
• Phase four: acceptance and deployment.
  

5. System structure

The system structure section shows which parts (modules) the whole system consists of and who is involved (actors). Modules such as "order form", "product catalogue", "admin interface". Actors are various typical users - for example, a regular visitor, a registered user, an administrator..

Example:

• Module
  
• Module
  
• Actors:
  
  • User (makes a reservation)
    
  • Administrator (manages capacity, confirms orders)
    

6. Outlined architecture

This is not a deep technical design (that will come later), but a sketch of how the system will work internally - how the different parts will communicate with each other, where the database will be stored, whether the system will be divided into frontend and backend, what the logic between them will be.

This gives the client an idea of the complexity of the solution and whether it fits their needs and capabilities.

7. Method of acceptance

One of the most important parts! This is where you describe exactly how the handover of the work will take place. What everything must be tested, what the checklist will look like to verify that the work is complete. When the checklist is ticked off, there is no room for guesswork as to whether everything is ready for handover and the work is accepted without reservation.

Example:

• User login and logout works
  
• The user can create a new booking
  
• Email confirmation arrives within 5 minutes

8. Risks listed

This section assesses what could cause complications - e.g. dependency on third parties, slow decision making by the client, integration to external systems, etc. This section is important for everyone, because even a well-planned project can run into obstacles that are good to name in advance.

Example:

• Integration with a third-party mail service can fail if they change the API.
  
• Late delivery of documents from the client can cause a delay in the delivery date.

What is not a software specification?

A software specification is not just a specification from the client. If a client sends an email saying they want a "capacity management reservation system", that is not a specification. Neither is a list of features written in Excel or a mind map or wireframe, although these things may be part of the specification.

A real specification is a complete document that describes not only the features, but also their boundaries, environments, test scenarios and acceptance conditions. Most importantly - it must be signed or at least agreed by both parties. Otherwise it has no weight.

What good is it?

For the client, the specification brings major benefits:

• They know exactly what they are buying.
  No confusion about what will and will not be delivered.
  
• Gives a level playing field in the tender process.
  If the client decides to approach multiple companies, they can take the specification and put it out for pricing. They are all then competing for the same thing - not their interpretation.
  
• It prevents inflating the price during development.
  If something is not in the specification, it can be reasonably quantified as a multiple cost. However, once what is in the specification is written in, the supplier must develop and deliver.
  
• It ensures a smooth handover.
  With acceptance conditions, it is clearly stated what is to be tested and under what conditions the work will be accepted without reservation.

How we do it at TRITON IT

For larger contracts or tenders, we create a software specification as a paid service. The client can then take it and give it to anyone else - let multiple companies price the solution. If we win the tender, we deduct the price for the specification from the total price. In practice, this makes the specification free for the client.

At the same time, we don't insist that we have to do the specification. If the client prepares it themselves or with another supplier, that's perfectly fine - but we always want to see it. We don't go into development without it.