Documentation allows you to preserve and communicate project information. It is instrumental if you need to review some forgotten information before introducing new features or changes in the software. It also adds great value during technical discussions as it is always better to talk over a standard diagram that everyone can see.
When software documentation is required in any stage of software development, it is essential to know what to document and how to document it. If formal documentation is required to represent the information, it will be necessary to rely on standards. On the other hand, if informal documentation is enough, it is important to understand what to do and how to communicate that information.
Software documentation can be generalized as a set of artifacts that describe how the software works. There are two types of artifacts: text and diagrams. Text examples are: requirements document, test plan document, README files, etc. While diagram examples are: architecture diagrams, sequence diagrams, etc. In the end, documentation is a way to present and preserve useful information for ourselves, the client and the team/colleagues.
What level of detail should we put into documentation?
The answer depends on several aspects:
- Client needs: It is possible that the client doesn’t require any documentation at all, or, in contrast, it is possible that the client requires full documentation of the software, based on standards.
- Available time: time is always important in any software project. If only one day is available to document, we will probably focus on writing only a README file.
- System/Project/Code complexity: complexity is going to require different types of documentation. For example, a simple API can be documented with a simple Swagger or a text document, while a complex satellite software system will require several PDF documents and diagrams.
- Software methodology: the work methodology we choose, like Scrum, Waterfall or Kanban will involve different documents as well. In the Scrum methodology, the Product Backlog, the Sprint Backlog and the tickets are documents per se (they contain valuable product information). In the Waterfall case, it will be necessary to document requirements, analysis, design, code (through comments) and tests as part of each software development phase. Finally, in the Kanban case, tickets are considered a universal task tracking for documentation.
- Formality level: Formal documentation will require standards to be applied like UML, while informal documentation can be any document (a .txt file, a drawing, e-mails).
UML and SysML standards
In terms of standards, UML and SysML must be considered. UML is the Unified Modeling language for software. This standard should be necessary and sufficient to document any kind of software, but it is not possible to document systems with some hardware and software components. For this reason, SysML appeared in 2007 as a standard for systems documentation.
In UML there are two important diagram types: structure and behavior. Structure diagrams show “a picture” of the software in a particular moment of time. Some examples are: architecture diagrams and class diagrams. On the other hand, behavior diagrams show how the information flows and how it is transformed step by step. Some examples are activity diagrams (wrongly called “flow diagrams”) and sequence diagrams.
In SysML the structure is the same, but it is important to mention that the class diagram was reused to create the Block Definition Diagram (BDD) and its derivative, the Internal Block Diagram (IBD). BDD shows the system architecture and the IBD takes a particular block of that architecture, and it describes the internal components. Also, SysML introduces the requirement diagram (useful to document hundreds of requirements) and the parametric diagram (useful to show mathematical rules in the software flow).
The shared diagrams between UML and SysML are: sequence diagram, state machine diagram, use case diagram and package diagram.
Choosing the right level of documentation
As already mentioned, non-standard documents can be useful as well, mainly when time is short and a deadline is very close. In this case, even a drawing on paper and a picture are useful to document.
There is no rule in any standard stating what is the minimum documentation needed for a particular piece of software, because as explained before, it depends on several aspects. Nevertheless, there are some points to be considered on this topic. Universally, any software should be documented with requirements/features document, the solution provided and tests/validation performed. This is necessary to describe and close a complete product delivered to the client.
An application should have at least a README file describing how to install and how the application works. Also, as a recommendation, an Activity diagram and a Component diagram can show the internal information flow (steps) and the general architecture of the software. The next example shows a simple software architecture with a component diagram. Application 1 is connected to Application 2 with the HTTP protocol. This API contains 2 internal components: Application 3 and the Database.
Also, Deployment diagrams are useful to show the topology and deployment of applications. In the picture below there is an AWS Cloud Architecture diagram:
Documentation organization and communication
Finally, communication is one of the most important steps in software documentation. Any type of document is useless if it is not properly communicated. A good practice is to use a repository folder and place the documentation inside the a /doc folder. For example, an architecture diagram can be placed in:
Name, date and version are important to keep track of versioning and to avoid future confusions. If someone asks for a particular document or diagram, the repo link can be shared instead of searching and forwarding old emails. Of course, emails are really important and the most used feature to communicate. In this case, attached documents must be as formal as possible (suggestion: PDF, png format).
In conclusion, documentation time should be considered in any project schedule or task planning to improve a released product and to avoid future documentation and communication issues with the client. It is important to keep it simple, but with the maximum formality level as possible.