— 4 min read
Edit post on GitHubWhenever I speak with developers at conferences and they ask about the topic of software documentation, most answer with the following sentence.
Well, we had to finish it quickly, and there was no time left for documentation.
But is documentation essential or not, and what should we know about this topic?
In my experience, most developers underestimated the value of proper software documentation. Back in the time as a junior developer, I also took every opportunity to avoid documentation. So the documentation for certain features was the code and me.
As you can imagine, this behavior leads to many problems, and I had to realize that the code alone is not enough. Especially if you want to take a vacation or need additional developers in the team, missing documentation is terrible from my point of view.
Unfortunately, writing documentation is not much fun as building new great things for the customer. For me, as a developer, documentation, and communication have become one of the essential skills a good software developer needs. But what does it mean to attribute proper documentation, and what is the minimum requirement for us as developers? This question I try to answer in the next section. There are many articles about software documentation and literature. I will summarize things that help me to write better documentation.
The first thing I had to understand was that documentation valuable for your customer and team. This enlightenment helped me to get a better feeling if I have to write documentation.
For new documentation, I try to be a focus on for whom I write the documentation. A typical project team consists of a vast number of stakeholders, including customer employees, product owners, developers, and many more that are needed to develop a project successfully.
If we define the team in this way, we quickly realize that we need different documentation for the different roles.
These are just examples to show how different documentation can be. With the help of the following questions, you can put yourself in the role of the person.
In my experience, a little documentation focus on a problem is better than a 70-page document that covers all aspects!
Variation of questions and example answers:
Readable documentation
From my perspective, software documentation is sometimes not readable, or I can not find any useful information. I search for a way to make my docs better. I found Beth Aitman's blog post.
She has a great strategy:
The full talk you can find at:
Example of cupcakes backing documentation:
This example shows that a structure helps the user to understand what he gets after backing. Add helpful graphics and pictures in the documentation!
For architecture communication and documentation.
I started using the templates from arc42. This template helps to have an excellent structure for this kind of documentation.
Example Table of Contents by arc42:
The Templates you can download at:
In my opinion, excellent software documentation should have the following characteristics. Maintainable, this means easy and quick to adjustable. Up-to-date and correct all changes need to be written down. Understandable and readable you should use the same terms every time and have explanations of terms. Focus on the target group of readers answer, the questions of your readers, the documentation should help get things done! Compact and low cost concentrating on the essential facts for your reader.
Lars Roettig is a Senior Software Engineer at TechDivision GmbH. digital agency focused on Adobe Commerce and modern web development. My personal goal is to teach you how to write stable software with quality.
Learn more about Lars