The importance of documenting your system (and using the documentation)
There was a time when documenting the system meant adding comments to the code. When a developer needed to recollect how a particular functionality was done, reading the comments in the code was enough. Well, it might make some sense when the system is simple and the development team is small. However, for large projects and big companies, the reality is completely different. There are various teams working in parallel with different modules, and it’s difficult to track all the changes being done and make everyone aware of them.
As software becomes bigger and more complex, the only resource that can help developers, testers, and product owners to keep track of all existing features, restrictions, and parameters is a good knowledge base, which can be translated into system documentation. However, such documents usually do not exist or, if they do, they are not updated or viewed frequently. Over time, such documentation becomes useless and it’s ignored by the whole company for not reflecting the current design of the projects. Besides, no one gets encouraged enough to “fix” the documentation, since it may sound worthless.
System documentation not only provides guidance for the whole team and users, making the development and testing easier, but it also becomes excellent training material for the company’s newcomers and new customers.
This article goes through the classic Five Ws (what, why, when, where and who), plus, a “how” to detail the importance of documentation and actions to keep it up to date with little effort.
To begin with, system documentation is a set of documents that details every existing resource of the project, followed by a detailed explanation, dictionaries, and examples. This set of documents can be classified into different areas of the system: product (functionalities), specifications (prerequisites to use it), end-user (tutorials for customers), and processes (companies’ internal patterns and standards). As noted, when properly employed, documentation can provide useful information for every role in the company, and could be compared to an internal “search engine”.
Documentation normally consists of web pages shared with all collaborators, so they can view, edit and watch modifications. For this reason, this type of documentation sometimes is referred to as “Wiki” by some companies, as a light reference to Wikipedia, where anyone can contribute to the content.
There are many reasons to create and maintain the system’s documentation. First, let’s break the silence: as the software gets bigger and more sophisticated, it’s almost impossible to remember all the pages, screens, settings, parameters, restrictions, and especially the business logic of every functionality. Even if a developer and tester worked on a specific feature in the past, it’s very unlikely that they will remember all the conditions after two or three years, or maybe even less than that. Let’s keep in mind the simple fact that we are humans, and we have a limited “amount” of memory available to remember long-dated events. Documenting the system is a measure to protect the memory from forgetting what was implemented, thus, saving plenty of time trying to remember how the functionalities work. And, as you already know, saving time is saving money.
Secondly, many software development companies have a similar problem: some specific pieces of code can be understood and maintained only by a specific group of developers. I know it probably rings a bell with you. When a functionality needs to be fixed or improved, it goes straight to a particular developer, who has initially implemented it. This developer, then, becomes the only one who can interpret the logic behind it. This is an effect called “Code Ownership”, which takes to the classic phrase that every development team has probably already heard: “If that developer leaves the company, who is going to work on it?”. Instead of arranging training, workshops, and presentations to spread the knowledge (which consumes time), this effect can be easily resolved by using system documentation. In other words, if the functionality is properly documented, anyone can work on it. It will not only eliminate the Code Ownership effect but will expand the knowledge throughout the development team(s).
Moreover, documentation helps the company’s newcomers to understand the system’s basics and the aspects of how processes are executed in the company, especially in terms of methodology, estimates, hierarchies, and ceremonies. In this case, it works as training material and may minimize their learning curve, which means that new developers can start working on the software sooner than expected.
This is a company’s particular decision. System documentation can be maintained by developers or testers right after the functionality is modified. As they coded and tested the functionality, they have all the relevant information to add to the documentation, including the restrictions and caveats. No one will have the same background as them, so, the least they can do is expose this background in a form of documentation. After that, this documentation is viewed by the support team (to set the functionality up for the customers), product owners (to prepare presentations), other developers (who will fix or improve it), testers (to validate test cases and write automated tests) and infrastructure engineers (to build hardware/software required specifications).
Alternatively, the company can “create” the role that will presuppose writing documentation and assign it to a collaborator, who will be responsible for feeding it and checking if the existing documents are still valid. In some cases, documentation might also be updated by product owners, since they are aware of what has been agreed with stakeholders and often give them presentations of new features.
As soon as possible! For instance, for product documentation, when any functionality is improved, changed, or fixed, a developer or a tester should be responsible for updating the corresponding section of the system’s documentation. As part of the team’s process, it can be added as a step of the quality assurance or even part of the “Definition of Done”, in case the company uses agile methodologies. This is one of the keys to not letting the documentation gets outdated. If it’s not part of the process, it’s very likely that it will be forgotten and, as consequence, be ignored in the future.
Although documentation can be presented just in the form of simple documents shared with the whole team, there are exclusive (and excellent) tools to document software, which provide good opportunities for collaboration, rich text formatting, cross-linking, instant searches, attachments, and integration with third-party applications, such as version control systems and file storage platforms.
Documentation is often stored on the company’s local servers which should be backed up with high frequency given the importance of the documents. As an alternative, there are also cloud solutions, that companies can use to build their own infrastructure.
Most of these tools can be found, evaluated, and acquired online, such as Confluence, GitHub, Nuclino, ProProfs, Notion, and Sharepoint (if the company uses Office365 business).
There is no single structure for the company’s documentation. Each company has different projects and processes, which results in different patterns of documenting the system. However, there are some aspects that should be common among them: clear communication, formatting, and glossaries. Using product documentation as an example, it’s recommended to include at least the following sections:
- Purpose of the functionality (the issues that it solves and set tasks)
- Features (a list of operations that the functionality provides to the final user)
- Workflow (how to get to the functionality in the application)
- How to set it up (settings, devices, drivers, and additional software needed)
- Parameters (keys, files, or flags that change the operations)
- Known errors (and how to act if they appear)
- Technical details (modules, packages, classes, components, and libraries used)
- Changelog (if applicable)
Also, it’s extremely important to write the content using clear language, avoiding abbreviations, informal titles, low-level terms (technical), and imprecise information which has not been verified yet. A good suggestion is to have in mind that someone who has no knowledge or experience of working with a system will land on the page and try to understand what it conveys. If specific business logic-related terms are used, do not forget to provide a glossary explaining each of these terms. That’s what cross-linking is for!
Take advantage of rich formatting: add headers, tables, images, attachments, internal/external links, and text styles to highlight important aspects. A well-documented page is pleasant to the eyes and increases the chances for the readers to understand most – or all – of the provided content.
Creating hierarchies for the pages is a good practice as well. Every page should be placed under its corresponding section, which can be based on the application’s modules, menus, versions, or other parameters such as region, country, customer, etc. Arranging the pages in a consistent and organized structure helps find the required information quicker. And also try to make use of labels, categories, and tags. They help filter pages and take the users directly to the page or subject they are looking for.
Types of documentation
Just a quick reminder that system documentation can be categorized into different areas, such as
- Product documentation: features and business logic.
- Technical specifications: hardware and software prerequisites to install the application.
- End-user documentation: generally used as guidance, tutorial, or training for the final users.
- Process documentation: methodology, estimation plans, schedules, and standards that the teams use.
- Hierarchy of the company: it lets the collaborators know who they should contact in any case.
There is a misconception that software documentation is needed only when the code is not properly documented. But there is no relation between these two types of comments. Comments on the code often reflect technical details, while software documentation covers all other aspects. Besides, testers, product owners, and support specialists generally do not have access to the code or, if they do, they do not know where they can find the necessary information.
There is another misconception that documenting software is a “waste of time since no one reads it”. That’s also not true. As mentioned in the “Who” section, different roles may need to have a look at the documentation – tomorrow, next year, or in five years.
If earlier it was considered that software documentation was optional, now it has become mandatory. If a company seeks to build cross-knowledge teams, remove dependencies and save time, it must allocate effort to create and manage good documentation. It’s not a spend. It’s an investment.