How to write proper Software Documentation?

#documentation #productivity

Whenever I talk to developers at conferences, I hear about the topic of software documentation mostly to the following phrase.Well, we had to finish it quickly, and there was no time left for documentation. But is documentation essential or not and what we should know about this topic?

Why is Software Documentation underestimated?

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 behaviour 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. 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.

Requirements for effective 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.

The editor wants to know how to maintain new features.
The product owner needs contact persons to coordinate the requirements.
The developer needs guidance on how to set up the development environment.

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.

Who has to read this documentation?
What needs the reader to know about this?
What will the reader get done?

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:

For whom am I writing this documentation?
- So that the editors can maintain the content without help
What do I want to document?
- A process of how an editor can edit or change the content in the system.

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 blog post

Read Tip: Writing effective documentation - the Lead Developer Berlin 2019

6 Tips to make your software documentation great!

Link: https://bethaitman.com/posts/tld-2019/

She has a great stragigie I try it out it work well:

Write outline first
Add useful information in bullet point or nots to answering the outline
Add more details and than structure it

The full talk you can find at:

https://www.youtube-nocookie.com/embed/R6zeikbTgVc

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:

Introduction and Goals
Architecture Constraints
System Scope and Context
Solution Strategy
Building Block View
Runtime View
Deployment View
Concepts
Design Decisions
Quality Scenarios
Technical Risks
Glossary

The Templates you can download at:

https://arc42.org/download

Summary

For me should have proper software documentation the following attributes. Maintainable, this means easy and quick to adjustable if something is changed in the project. 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.