3 Key Aspects of a Good Documentation
In the tech industry, we heavily depend on all kinds of documentations in our day-to-day work. Whether we need to use a REST API, design a user interface according to a design system, or just need context to some code that has already been written, good documentation has the potential to improve the life of everyone working with it. Bad documentation, on the other hand, often leads to confusion and uncertainties.
So following question naturally arises:
What makes good code documentation?
In my opinion, good code documentation must be all three of the following:
- accessible
- authentic
- informative
Let’s discuss these aspects in a bit more detail:
Accessibility
No matter how good documentation is, it is of no use if it can not be found or accessed by the people in need of it. Accessible documentation is something both the reader and authors can benefit from. For readers, this means being able to access a resource that contains the documentation, or owning a physical or digital copy of the documentation. However, one problem for readers who own copies of documentation is that this documentation will be out-dated as soon as there are any major changes in the process. This is not ideal and contradicts our “accessibility” principle.
For the author, two things are decisive with regards to accessible documentation:
- Locating the documentation close to the project (i.e, designs, code)
- Managing preferably only one piece of documentation
Co-locating documentation next to the actual project reduces the risk of forgetting to update the document after a significant change. In addition, managing only one piece of documentation helps to avoid potential duplication and stale information.
These two approaches can simplify the documentation process and subsequently enhance the documentation quality. Still, there is no guarantee of success. Authors must be aware of the importance of good documentation.
Authenticity
Documentation should always provide correct information and must be up-to-date. This is probably the biggest headache when it comes to maintaining a good document. Agile projects acquire a lot of changes during their lifetime. Such projects don’t really seem to have a clear end, which is why maintaining good documentation can be quite hard. Although it is true that not every change requires updated documentation, many changes do in fact require this action. It’s not easy to be aware of every change and the areas that are affected by these changes, especially when it comes to code.
However, this shouldn’t be an excuse for out-dated documentation or documentation that contains incorrect information. Maintaining good documentation is just as important as writing good, high-quality code. Perhaps even more important, as people rely on it for instruction.
Informativeness
Every piece of information should be relevant and understandable to the reader. It is important to keep in mind who your target audience is to ensure the documentation is relevant for potential readers. Depending on the project and documentation, contributors can include designers, testers, administrators, project managers, developers, or maybe even casual users who are trying to make use of a tool. One shouldn’t assume knowledge or context on a certain topic without introducing the reader to said topic; unless, of course, one can expect the reader to have that knowledge. This may seem like an obvious fact to some readers, but this is not always the case.
Maintaining documentation can be quite cumbersome and challenging, but it doesn’t have to be. Sticking to these principles can enhance the user experience of any documentation.
We now know what we need to focus on when creating project documentation. The next blog post will provide examples on how to put these principles into practical use. Stay tuned…
