[COMITAS]
Contact form
Book a non-binding appointment with
Contact
We are available between 8:00 and 18:00 and will get back to you as soon as possible. Find answers to your questions!
Introduction to IT Documentation
An important yet often overlooked topic is knowledge documentation, particularly software documentation in IT. In this article, we focus on documentation created by individuals (architects and developers) and teams involved in development. Documentation related to processes and requirements is excluded, as there is already plenty to explore within pure software documentation.
We often jump into an existing, active project or take over the maintenance and support of applications, only to find that the documentation is either missing or insufficient. This is a very common experience for developers. But why is this usually the case? There are several reasons.
Speed Speed is key, and software development is constantly accelerating. Feature output is often overemphasized, so topics like documentation are considered "insignificant or negligible" and are inevitably neglected.
Complexity – Requirements and software solutions are becoming increasingly complex, and so is the maintenance and creation of documentation, which takes additional time.
presentation – Diagrams and drawings of software applications are usually not very clear and updating them is sometimes very time-consuming, so they often become outdated during further development and are not always updated.
codes Developers want to implement interesting features and applications and usually focus their efforts on that. Documentation is perceived as boring, which is why it isn't always created promptly.
All these points contribute to the fact that special attention should be paid to ensuring that the software documentation is created and continuously maintained.
With all the effort and time required, we should ask ourselves: Why bother at all? Why is software documentation important? The following points illustrate its relevance.
Onboarding new team members: Every time a new developer joins the team, good documentation helps with quick orientation and does not require a significant time investment from other team members to impart a good basic knowledge about the project.
Regulatory requirements and audits: If the software you are developing is subject to external or internal audits, or is affected by any regulatory requirements, then good documentation significantly facilitates the work with the auditors. Sometimes, documentation is even a strict requirement for an audit.
Communication with all stakeholders: Good documentation enables all types of stakeholders to understand the software in the context that interests them. If the documentation takes into account the different types of stakeholders and carefully adapts the wording to be less or more technical, the team saves a lot of time that would otherwise be spent explaining and translating the features of the software system to everyone.
Features of the software documentation
Good software documentation has the following characteristics, which make it possible to cover all the requirements of modern development cycles:
Easy: The documentation should be simple and minimalist to reduce maintenance and ensure that all involved parties can understand the core aspects.
Holistic: Different types of documentation readers require different contexts. Good documentation should consider all stakeholders and ensure that everyone can participate and understand.
Reusable: The structure, vocabulary, and model of software documentation should be reusable for new software projects; therefore, a structured yet flexible documentation model is very useful.
Automated: To ensure that the documentation is maintained over time and has minimal impact on the development teams, most diagrams, tables, and specifications should be automated as much as possible.
Mobile: It should be easy to create and distribute the documentation independently on any hosting medium.
Implementation: In this section, we will examine various tools, frameworks, and documentation models to meet the documentation requirements. We will focus on specific tools and standards that can be used to implement our strategy. Please note that for almost every tool, framework, or standard, there are alternatives. We will present a few common solutions for each requirement.
Implementation
In this section, we will look at various tools, frameworks, and documentation models to meet the requirements for documentation properties.
We will focus on specific tools and standards that can be used to implement our strategy. Please note that for almost every tool, framework, or standard, there are alternatives. We will present a few common solutions for each requirement.
Easy
To keep documentation simple, we need a suitable medium. Most documentation these days is either in MS Word or PDF. For those who like to experiment, there's also Markdown, which offers developers some advantages over text editors.
The Markdown Guide: A free and open-source reference manual that explains how to use Markdown.
Automated
PlantUML PlantUML is a tool for creating diagrams. Diagrams in PlantUML follow the "…as code" movement, where the diagram is generated on the fly from a domain-specific language. This is very useful and allows all online documentation that references a central diagram repository to be updated automatically.
To automatically document API resources (REST) or methods (RPC), we can use documentation generators like Swagger, which generate documentation from code comments or API spec.
swagger It eliminates the manual work involved in API documentation, offering a range of solutions for generation, visualization, and sharing.
Finally, the documentation for a specific software project should be encapsulated in its own repository belonging to the same software project. The automated creation and deployment of documentation artifacts should be part of the CI/CD pipeline. By automating as much as possible, you ensure that the documentation is maintained over time.
To make the 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 we find helpful in defining the documentation framework:
Arc42 It is a template for communication and documentation. It creates a framework and structure that helps to put topics into the right context and to address different stakeholders appropriately.
The C4 model It helps with structuring 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.).
Mobile
Our existing documentation is based on open standards and uses flexible and powerful open-source tools. Now it's time to make it available to everyone involved.
To make the documentation portable, we need to be able to generate it from our Markdown files and present it in an easily consumable form. The best way to do this is to provide the documentation as a web page, based on static files or HTML that is generated on the fly.
docsify is ideally suited for providing documentation that is converted from Markdown files to HTML and is based on a few simple configuration files.
Summary: Key takeaways about intuitive eating
The following diagram shows how a centralized documentation repository per product or project could be used to maintain software documentation that contains files from various 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 article, we have outlined the characteristics of good documentation (simple, comprehensive, automated, reusable, and mobile).
Additionally, we've presented a few tools that can support us in creating, maintaining, and publishing software documentation. For questions and feedback... We are happy to assist you..