Blog

Documentation and specification

09/11/2023

Documentation and specification

In software development, you probably heard about the terms documentation and specification. As usual, they might have different meanings based on what project you work on, what company, or even what team. For this and the next stories, we would like to put a clear line between these two. 

Documentation 

How many times have you faced a situation when you do not know how code works? Or maybe you do not know how applications are built? Software architecture? Test framework?

These and many more are part of the documentation. This kind of describes what exactly is in your project. It might describe some recent past, but practically it tries to document (sic!) the situation in your project, in your code, or in your deployment.  

 

 

 

The aspect of being up to date is very, very important. For comparison purposes – let’s consider you are opening your bank account, and it has information from 7 days ago. Ridiculous, right? In such a case you cannot trust this information at all. 

This is how important it is to have documentation up to date. People need to trust that it contains actual information, and they rely on this. They can plan the next steps, they can share information with others, and they can much more easily find what might be wrong in the code. Or even in the documentation itself! If people have trust in documentation, then they can challenge what is there and expect it to be fixed. If they do not have it – they start to stop caring about it, which leads to less useful documentation, which leads to stop caring, which leads…

Do you see where it leads? 

Documentation needs to be up to date. If you lose it, it is like losing trust – it is really hard to get it back. 

Specification

Developers are coding, but how do they know what to code? And if they are coding, how to be sure that it is what the customer wants?  

This is where specification comes in. It describes what (also how, and when, but we’ll back to this in a separate story) is needed to develop. This term is even broader than documentation.

Have you heard about user stories, use cases, requirements, acceptance criteria, etc.? Even if they have all these names, they can treat them as part of the specification. Practically, it contains information for all other parties in the software development process (product owners, project managers, testers, developers, etc.).

Companies often have dedicated teams for such jobs, because there are many important aspects – talks with customers, analysis, deep knowledge of existing systems, and even finding a compromise! 

 

 

What is important is that while documentation is a living document, specification documents may reach the end of life. In other words – there are parts of the specification which do not need maintenance. They need to be created to find an initial solution, have a decision written on paper or they are just to inform the customer what scope of application is proposed. 

Specification is a very important step in the software development process. While not all projects require detailed documents about interfaces, architecture, and so on, there will always be a need to have initial statements on paper to know what to develop. It is crucial to find this compromise, what is needed for my project and what can I drop and leave to the developer’s decision. 

At RSC, we will help you find this compromise. 

PS. If the specification describes what to do, and documentation of what we have – is it possible that they met at some point? Short answer – yes. Long answer – we will cover that in the next stories.