Software Documentation: What Customers and Contractors Should Remember in 2024

• Importance of documentation in software development
• What is Technical Documentation for software?
• Software requirements documentation
• End-user documentation
• Types of Technical Documentation
• Samples and templates for software documentation
• How to create documentation for a software project: basic guidelines
• Conclusion
• FAQ

Technical documentation for software deserves the attention of everyone involved in producing and maintaining IT products: developers, customers, and technical support staff. In this article, we will go over this issue, comment on best practices, and provide a number of relevant practical recommendations to consider when working with technical documentation. We hope that you will be able to compare your own experiences with our thinking on documentation, and be able to take something away that will help you in crafting your own.

Importance of documentation in software development

When it comes to stressing the importance of documentation in software development, it must be assumed that a great deal of novel information is generated organically during the creation of any new software. This information is valuable to customers, development teams, and those who will go on to maintain or use the product in future. Without being properly recorded in documents, this information can be lost, distorted, or forgotten.

Given the scale and often complex dynamics of development projects, documentation reminds project teams of the characteristics and details of both processes and product. This is especially important for large projects with a lot of code and a large team.

When answering the question of why create software documentation, it is important to realize that an insufficient quality of documents can disrupt the ideal maintenance, updating, and scaling of any product.

Amongst other undesirable consequences, where there is an absence or poor quality of documents, you may encounter difficulties with transferring a project to another team or customer; protracted and painful onboarding of new specialists; sudden failures in pre-existing parts of the system; missed deadlines; budget overruns, or hasty and error-prone development of new features. In most cases, where documentation has not been up to standard, the true scale of any issue becomes clear only after they have done damage.

It goes without saying, then, that poor software documentation can negate the efforts of developers and disappoint clients. Due to any shortcomings in documents, customers may suffer financial losses, and project teams are likely to be forced to seriously slow down the pace of their work. It should also not be overlooked that, according to surveys, 34.7% of developers indicated that poor documentation represents one of the most significant challenges they face at work, further reinforcing the importance of software documentation in software engineering.

What is Technical Documentation for software?

Software documentation consists of documents, including texts and images, that contains information about the creation, characteristics, and properties of an IT product.

Software documentation can be grouped into components as follows:

• Software requirements documentation. This reveals information about the purpose, capabilities, and functionality of a system. The system’s business logic and the product’s key features should become clear from reading these documents. User stories, acceptance criteria, and the principles of interaction with users are also outlined in such documents
• Technical documentation is the main source of information about any software, including its code, APIs, algorithms, etc. These documents describe all aspects of how the software has been designed and is operated 
• End-user documentation. These are manuals, instructions, guides, and other information intended for those who use the software.

Another approach to classification categorizes software documentation into two broad types: process documentation and product documentation.

• Process documentation refers to the software development process and covers all its phases, from analyzing and forming software requirements, through to the deployment of the finished system.
• Product documentation describes the principles of the product’s construction, as well as its parameters and components.

Before delving into the details of technical documentation, let’s briefly review software requirements documentation and end-user documentation to avoid any confusion.

Software requirements documentation

As previously mentioned, this part of the software documentation compiles all information related to functional and non-functional requirements, domain logic, and software interaction with the user. There are numerous types and models of such documents in the development sphere, and their usage often depends on the specific project management methodologies applied. For instance, the business requirements specification (CONOPS) and its adapted version, the software requirements specification (SRS), are commonly used. If the project team adopts Scrum, then one of the main documents is the Product Backlog, which comprises Epics and User Stories. Acceptance criteria can also be outlined in the Product Backlog, which defines the requirements against which the completion of a User Story can be fulfilled.

Furthermore, consider using notation systems and modeling languages that describe technical and work processes via graphical depictions of system design, as these can be extremely useful when preparing documentation.

A typical example of this would be Business Process Model and Notation (BPMN), through which a project’s work processes receive graphical representation. In BPMN, elements are laid out in diagrams and schemes and allow for the display of a development’s technical details. Similarly, Unified Modeling Language (UML) visualizes the design of a system using sets of diagrams, in turn providing clear understanding of any created product though the complementary use of text and graphics.

It is essential to use common solutions such as BPMN and UML in documentation, because it makes it more likely that those who will be working with the documents will encounter notations and diagrams already familiar to them. It should also be noted that crafting documentation can be an evolutionary process, where examples that have proven themselves useful in practice can be replicated, tailored and improved upon for future projects.

Roles and responsibilities for writing software documentation vary across project teams. Typically, a specialist in the respective field is assigned for each type of documentation, such as a business analyst (BA), tech lead, tester, etc.

The software requirements documentation also encompasses documents from the following development project areas:

• User interface (UI) and user experience (UX) design documentation. UX documentation covers all key stages and elements of UX, including a UX style guide; user personas and scenarios; scenario and user story maps; sitemaps; wireframes; mockups, and prototypes. User interface documentation is concerned with the end user’s interaction with the software, and these documents describe all possible user actions, including all visual, audio, and other elements of interaction. Examples of such documents are UI — style guides; component descriptions; prototypes; user access tables, etc (Information Architecture, JTBD, CJM, Color System ).

• Quality assurance documentation. This part of the documentation covers all aspects of testing and confirms the quality of any created software. This documentation provides an important list of standards and requirements with which the product must comply. In such documentation, a quality management manual and a test plan are often drawn up, and the actual execution of tests and any test results must also be documented. Bear in mind that software testing documentation is a much broader topic in itself that will be covered beyond the scope of this article in other studies.

End-user documentation

Every one of us, as software users, has undoubtedly encountered various forms of end-user documentation. This includes user guides, manuals, and more. Lately, there’s been a surge of innovation in this field. Notably, the emergence of video tutorials, embedded assistance, and support portals enhances user experience and understanding. Leveraging tools such as FAQs is particularly useful for maintaining a positive user experience.

In this article, we will not touch on other types of documentation that you may have encountered, such as project management documents that deserve to be considered in a separate study. Rathermore, here we will focus on the technical documentation of software products, considering exactly which documents to have, how to create them, and how to work with them. Let’s take a closer look. 

Types of Technical Documentation

As indicated above, technical documentation for software actually combines many documents that are diverse in terms of content, purpose, and format. The main types are:

• Software architecture design documentation. This consists of documents that record the principles of building a system, specify its components and their purpose, as well as detail any key decisions. Furthermore, this type of documentation describes the connections the software has with the environment and the data flows present within the system. It is important that the main architectural solutions are listed, their technical specifications are given, and that design principles are outlined. In addition to schemes and tables, it is desirable for such documents to contain a textual component that explains exactly what has determined the choice of architectural solutions, as well as what role is assigned to individual elements of the architecture ( Confluence, Site map, Sequence diagram).

• Documentation of the APIs (Application Programming Interfaces) used in the development and instructions on how to use and connect to them effectively. In this context, it makes sense to pay attention to tools like Swagger, which automatically generates and updates API documentation, keeping it up to date. The project team should create a list of all APIs that could be used in further development, with specifications for each of them. In addition to APIs, it is advisable to create documents regarding other elements of the software development kit (SDK) — a set of development tools ( Swagger 1, Swagger 2).

• Source code and technology stack documentation. It is not sufficient to simply provide code itself, it is also necessary to explain how it was created and how it works. Consider the following points: if a code writing guide has been adopted by the project team, then it should be included in the documentation set; documentation should fully describe all frameworks used for the back-end and front-end, indicating the specifics of such use; if content management systems (CMS) and content management frameworks (CMF) are important within the developed software, then it is imperative to describe them and the conditions for their use; any applied design patterns, plug-ins, tools or other solutions which were not developed independently but obtained from external libraries also require description, and finally, remember that any security rules established on the project also need to be documented. In general, this part of the documentation is critical for the successful ongoing functioning of the software product. Therefore, ensure that nothing essential is left out. Any principles, internal dependencies, and relationships of a created system are subject to documentation ( Microservices, Server Architecture).

• Installation and deployment documentation. Such documents are necessary for any software already in use. Often, full operation of programs is not possible without integration with other systems or databases, and the main details and features of any such integration should be documented.
• Quality assurance documentation. This part of the documentation covers all aspects of testing and confirms the quality of any created software. This documentation provides an important list of standards and requirements with which the product must comply. In such documentation, a quality management manual and a test plan are often drawn up, and the actual execution of tests and any test results must also be documented. Bear in mind that software testing documentation is a much broader topic in itself that will be covered beyond the scope of this article in other studies. 
• Maintenance instructions and manuals. This information is targeted primarily towards those who will maintain software and serve its users. These documents should contain a list of the most typical problems encountered in the functioning of the system and provide methods for solving them. Any mutual connections and dependencies, either to be found within the system, between its parts, or between the system and the external environment should also be presented here. Incidentally, remember that it is possible to customize documentation to specific categories of technical specialists who will deal with the software in different ways. For example, it is appropriate for DevOps engineers to provide a separate reference book with answers to frequently asked questions, to prepare instructions for installing, deploying, and updating the system, as well as provide a description of its functionality. 

Here, we have given only an approximate structure of technical documentation in software development, briefly commenting on each of the sections. The list, content, and format of documents should be specified based on the scope and parameters of any given software product.

Remember also that not every project requires the creation of all of the documents listed above, and for smaller projects it is often enough to write descriptions of the technology stack and API, as well as instructions for deployment. Broadly speaking, it is advisable to create only useful documents without which it would be impossible to proceed, but a general rule of thumb to bear in mind would be that the larger the project, the larger and better its documentation should be.

Samples and templates for software documentation

Long-standing IT companies definitely prefer to use their own software documentation templates. However, evaluating examples of software documentation can prove extremely useful for development customers who wish to assess the completeness and quality of documents prepared for them by their contractors.

Many process documentation software products contain such templates, providing for the possibility of customisation. Among such tools, it is worth paying attention in particular to:

I am pleased to share my company’s unique experience with software documentation. Like all seasoned developers, we too have our own established process for compiling documentation and templates tailored to each phase of the project. This includes conducting stakeholder interviews, assessing project parameters, and creating low-fidelity prototypes, among other activities. To ensure accuracy in these project parameters, our Business Analyst (BA) consistently performs functional decomposition.

How to create documentation for a software project: basic guidelines

It’s worth talking about the specifics of compiling software documentation in Agile projects.

Agile methodology does indeed acknowledge the importance of documentation, but it doesn’t place it at the forefront. As expressed in the Manifesto for Agile Software Development, there is a clear preference for working software over comprehensive documentation. However, it’s important to note that this does not imply a casual approach towards incomplete documentation in the Agile manifesto. Rather, it suggests that Agile projects afford more flexibility in terms of the schedule for creating documentation.

In a Waterfall project, all documentation is completed at the onset, and further work can only proceed once any finalized documentation has been approved. But with Agile, projects require a different approach to documentation. Let’s say you’re working within the Scrum framework. Most likely, you’ll initially create an amount of documentation corresponding to the functionality of the Minimum Viable Product (MVP). Your project might include several epics within the Product Backlog, and you would understand what documentation needs to be prepared as you work on each of them.

Therefore, as per standard practice, you should include documentation-related tasks in the respective Sprint Backlogs and continue accordingly. Initially, you produce the minimal documentation required to kickstart the project, and subsequently, over the course of development, you progressively produce comprehensive software documentation from sprint to sprint. The project team showcases and discusses the developed documentation, along with all other work results, during the Sprint Review and Sprint Retrospective meetings.

The features we’ve discussed enable the Agile team to align documentation creation with other development areas, ensuring that the documentation is pertinent to the current product version at each project stage.

There are some practical recommendations to consider when preparing documents. We advise you to:

• Have a balanced document list. Whilst your documentation should be complete and comprehensive, quantity does not necessarily mean quality. Duplication of the same information in different places should be avoided, and your catalog of documents should be thoughtful, structured, and easy to use
• Create documentation the way you would wish to receive it. Be mindful of those who will read your documentation by avoiding complex language and ambiguity. Do not be afraid to refine the document until it becomes clear, and make good use of visuals. Aim to achieve a unified style among all team members who write documents
• Consider the targeting of the documentation. Clearly understand to whom a document is addressed, and pitch the complexity of the text in terms of saturation of terms or the degree of detail based on the assumed technical level of your intended audience. Help the recipient of the documentation navigate it by compiling  a glossary of terms and abbreviations, and make use of cross-referencing between documents. Update documentation synchronously with software updates, where Version control tools will come in handy for you
• Carry out regular documentation reviews. Take into account any discussions you have at this stage and act on any appropriate feedback that comes in
• Encourage your team members to have, learn and develop their skills in preparing software documentation in software engineering
• Organize correct storage of technical documentation for software. We advise you to make Atlassian Confluence the main location for document storage. Backup copies can be placed together with code in software repositories
• Keep up to date with best practices and tools for software documentation in software engineering, feel free to test them and draw your own conclusions about the feasibility of further use. From time to time, noteworthy process documentation software enters the market. For example, it is appropriate to describe APIs with Swagger. This framework automates the creation of documentation about the API — the key element of any development project
• Remember that detailed and high-quality documentation is the mark of a mature development team. Pay attention to the topic of technical documentation for software during negotiations with potential contractors, and consider this factor when choosing a company to handle your project
• Make documentation one of your priorities when ordering software. Developers may not pay enough attention to software documentation, or may not be sufficiently incentivized to provide a complete set of documentation to customers. This is especially the case when a project is set to be transferred to another team or client staff. It is always the customer who suffers the most from a lack of sufficient documents, therefore, it is the customer who must ensure that documentation is created and constantly updated, as well as save it. Make sure that everyone involved in the project knows that documentation is not a secondary task.
• Keep documentation in mind when communicating with stakeholders. The relationship between software documentation and stakeholder communication is reciprocal. On one hand, stakeholder suggestions and comments can influence the documentation, often requiring updates and revisions. On the other hand, representatives of the client may express numerous of ideas and requests throughout the project. It is essential that these are meticulously documented to ensure accuracy and clarity in the ongoing process.It’s important to establish a format for documenting the client’s requests and preferences, akin to a «Client Wish List». Often, this method is used to record client feedback following the release of a new software version. Some of these requests may eventually be incorporated into the Product Backlog, while others may not be realized. However, it’s crucial to ensure that nothing is overlooked.
• Be aware of the value of Change log and use it. A change log is critical when dealing with continuously updated software, and it’s vital to record the reasons for changes in this log. Beneficial for both developers and technical support specialists, such as those managing a web resource, a change log provides a centralized location for all information about modifications, their reasons, dates, and the team members involved. It can also be used to log bug fixes. This vital document offers an organized, chronological record of alterations, enhancing transparency and communication within the team.

So, let’s recap. Having sufficiently detailed and well-maintained technical documentation for software is always important, but it becomes especially pivotal when a project is transferred from one development team to another, or to the customer’s employees. It is in these moments that the absence of certain documents and any negligence in their creation is revealed. 

That said, remember that any time during which preparation for a handover is taking place is a good opportunity to work on closing down any gaps in the documentation. It is obvious that without an adequate description of any technologies, architecture, constituent parts of the software product, its API, and deployment, then any project transfer will simply not be possible. It is also worth remembering that it is in the interests of the customer to insist on the correct drawing up of documentation in accordance with the requirements described in this article. 

The main criterion for evaluating software documentation is its sufficiency for the application, maintenance, scaling, and further development of software. If even one of those processes could be rendered impossible or even difficult due to poor-quality documents, then the documentation should be redone immediately.

Conclusion

In this article, you have learned about the types of documentation in software development and the content and properties of various documents. You have also received recommendations for creating documents that you can apply in your own practice, and you understand that the provision of quality documentation facilitates the maintenance, updating, and scaling of IT products.

At SECL Group, our teams consider software documentation to be an integral part of project work. Throughout this article, we have shared our views and experiences with documentation, allowing you to compare them with your own thoughts and testimonials. If you feel you still lack sufficient knowledge about software documentation or have doubts about the needs and content of certain documents then please don’t hesitate to contact us for comprehensive advice.

FAQ: