How to create and maintain good
An important and yet often not much considered topic is the documentation of knowledge and especially in IT of software. In the following article we focus on the documentation created by people (architects and developers) and teams involved in the development. We leave out the documentation around processes and requirements in the article, because there is enough to discover in pure software documentation.
So often we jump into an existing active project or take on application maintenance and support only to find that the documentation is either missing or insufficient. This is very often the experience of developers. But why is this usually the case? There are a few reasons.
Speed - Speed is key and software development is constantly increasing in pace. The output of features is mostly overweighted, so that topics like documentation are considered "unessential or negligible" and are inevitably neglected.
Complexity - Requirements and software solutions are becoming more complex and so is the maintenance and creation of documentation, which takes additional time.
Representation - Diagrams and drawings of software applications are usually not very descriptive and updating them is sometimes very costly, so they usually become outdated during further development and are not always updated.
Coding - Developers want to implement interesting features and applications and usually focus their activities on this. Documentation is perceived as boring, which means that it is not always created in a timely manner.
All these points contribute to the fact that special attention should be paid to ensuring that software documentation is created and also continuously maintained.
With all the effort and time required, we should ask ourselves: why bother at all? Why is software documentation important? Good documentation is important for the following reasons:
Onboarding new team members: Every time a new developer joins the team, good documentation helps with quick orientation and does not require an extensive time investment from other team members to provide a good basic knowledge of the project.
Regulatory requirements and audits: If the software you are developing needs to be subjected to external or internal audits or is affected by any regulatory requirements, then good documentation makes it much easier to work with auditors. Sometimes documentation is even a strict requirement for an audit.
Communication with all stakeholders: Good documentation allows all types of stakeholders to understand the software in the context they are interested in. If the documentation takes into account the different types of stakeholders and carefully adjusts the wording to be less or more technical, then the team saves a lot of time that would otherwise be spent explaining and translating the features of the software system to everyone.
Characteristics of Software Documentation
A good software documentation has the following features that allow it to cover all the requirements of modern development cycles. These are, in particular, the following:
In this section, we will look at various tools, frameworks, and documentation models to meet documentation requirements.
We will focus on specific tools and standards that can be used to implement our strategy. Please note that there are almost always alternatives to any tool, framework or standard. We will show a few common solutions to each requirement.
To keep documentation simple, we need a suitable medium. Most documentation these days is either in MS Word or pdf. For those willing to experiment, there is also Markdown, which has a few advantages over text editors for developers.
Markdown guide: A free and open source reference guide that explains how to use Markdown.
PlantUML is a diagramming tool. Diagrams in PlantUML follow the "...as code" movement. Where the diagram is generated on the fly from domain specific language. This is very useful and allows all online documentation pointing to a central diagram repository to be automatically updated.
To document API resources (REST) or methods (RPC) in an automated way, we can use documentation generators like Swagger that generate documentation from code comments or from API Spec.
Swagger takes the manual work out of API documentation, with a set of solutions for generating, visualizing and...
Finally, documentation for a particular software project should be encapsulated in a separate repository, belonging to the same software project. Part of the CI/CD pipeline should be the automated generation and deployment of documentation artifacts. Automating as much as possible will ensure that documentation is maintained over time.
To make documentation reusable, we need to agree on standards and best practices that all software projects should adhere to.
Here are some standards and models that I find helpful in defining the documentation framework:
arc42 is a template for communication and documentation. It creates a framework and structure that helps put issues in the right context and address different stakeholders appropriately.
The C4 model helps structure diagrams and visual artifacts for software documentation. It fits very well with the arc42 approach. A person represents one of the human users of your software system (e.g. actors, roles, personas, etc.).
The diagram below shows how a centralized documentation repository could be used per product or project to maintain software documentation that contains files from different repositories and assembles the software (e.g., in a microservices architecture).
Software documentation is very important but creating and maintaining it can be challenging. In this post, we highlighted what makes good documentation based on its characteristics (Simple, Holistic, Automated, Reusable, and Mobile).
Additionally, we've looked at a few tools to help us create, maintain, and publish software documentation. If you have any questions or feedback, please feel free to contact us.
Documentation should be simple and minimalistic to reduce maintenance efforts and ensure that all stakeholders can understand the core aspects.
The structure, vocabulary and model of software documentation should be reusable for new software projects, so a structured yet flexible documentation model is very useful.
Different types of documentation readers require different contexts. Good documentation should consider all stakeholders and ensure that everyone can follow along and understand.
It should be easy to create and distribute documentation independently on any hosting medium.
To ensure that documentation is maintained over time and has minimal impact on development teams, most diagrams, tables, and specifications should be automated as much as possible.
Our documentation so far is based on open standards, uses open source flexible and powerful tools. Now it's time to make it available to all stakeholders.
To make the documentation portable, we need to be able to generate it based on our Markdown files and present it in an easily consumable form. The best way to do this is to make the documentation available as a web page, based on static files or HTML generated on the fly.
Docsify is great for delivering documentation converted from Markdown files to HTML, and based on a few simple configuration files.