How to write proper Software Documentation?
Tags: documentation, productivity
Published: 2020-01-06 20:42:25

---
title: How to write proper Software Documentation?
published: true
date: 
tags: documentation,productivity
canonical_url: https://larsroettig.dev/how-to-write-proper-software-documentation
---

<picture>
        <source srcset="https://larsroettig.dev/static/fe0ba0877e14285fc241b9ef41337702/92d98/Software_Documentation_Teaser.webp 250w,https://larsroettig.dev/static/fe0ba0877e14285fc241b9ef41337702/c0ce8/Software_Documentation_Teaser.webp 500w,https://larsroettig.dev/static/fe0ba0877e14285fc241b9ef41337702/bc682/Software_Documentation_Teaser.webp 1000w,https://larsroettig.dev/static/fe0ba0877e14285fc241b9ef41337702/90b83/Software_Documentation_Teaser.webp 1280w" sizes="(max-width: 1000px) 100vw, 1000px" type="image/webp"></source>
        <source srcset="https://larsroettig.dev/static/fe0ba0877e14285fc241b9ef41337702/569e7/Software_Documentation_Teaser.jpg 250w,https://larsroettig.dev/static/fe0ba0877e14285fc241b9ef41337702/19e93/Software_Documentation_Teaser.jpg 500w,https://larsroettig.dev/static/fe0ba0877e14285fc241b9ef41337702/2705d/Software_Documentation_Teaser.jpg 1000w,https://larsroettig.dev/static/fe0ba0877e14285fc241b9ef41337702/7c07c/Software_Documentation_Teaser.jpg 1280w" sizes="(max-width: 1000px) 100vw, 1000px" type="image/jpeg"></source>
        <img src="https://larsroettig.dev/static/fe0ba0877e14285fc241b9ef41337702/2705d/Software_Documentation_Teaser.jpg" alt="Software_Documentation_Teaser" title="Software_Documentation_Teaser" loading="lazy" style="width:100%;height:100%;margin:0;vertical-align:middle;position:absolute;top:0;left:0">
      </picture>

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?

## <svg aria-hidden="true" focusable="false" height="16" version="1.1" viewbox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg>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.

### <svg aria-hidden="true" focusable="false" height="16" version="1.1" viewbox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg>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

<section><p><strong>Read Tip: </strong>Writing effective documentation - the Lead Developer Berlin 2019</p>
<p>6 Tips to make your software documentation great!</p>
<p>Link: <a href="https://bethaitman.com/posts/tld-2019/" target="_blank" rel="nofollow noopener noreferrer">https://bethaitman.com/posts/tld-2019/</a></p></section>

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:**

<picture>
        <source srcset="https://larsroettig.dev/static/995bc5134e829af195339c16ed5b9441/92d98/cupcake_sample.webp 250w,https://larsroettig.dev/static/995bc5134e829af195339c16ed5b9441/c0ce8/cupcake_sample.webp 500w,https://larsroettig.dev/static/995bc5134e829af195339c16ed5b9441/affd7/cupcake_sample.webp 934w" sizes="(max-width: 934px) 100vw, 934px" type="image/webp"></source>
        <source srcset="https://larsroettig.dev/static/995bc5134e829af195339c16ed5b9441/569e7/cupcake_sample.jpg 250w,https://larsroettig.dev/static/995bc5134e829af195339c16ed5b9441/19e93/cupcake_sample.jpg 500w,https://larsroettig.dev/static/995bc5134e829af195339c16ed5b9441/ad6c2/cupcake_sample.jpg 934w" sizes="(max-width: 934px) 100vw, 934px" type="image/jpeg"></source>
        <img src="https://larsroettig.dev/static/995bc5134e829af195339c16ed5b9441/ad6c2/cupcake_sample.jpg" alt="Example documentation for making cupcakes" title="Example documentation for making cupcakes" loading="lazy" style="width:100%;height:100%;margin:0;vertical-align:middle;position:absolute;top:0;left:0">
      </picture>

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:

1. Introduction and Goals
2. Architecture Constraints
3. System Scope and Context
4. Solution Strategy
5. Building Block View
6. Runtime View
7. Deployment View
8. Concepts
9. Design Decisions
10. Quality Scenarios
11. Technical Risks
12. Glossary

The Templates you can download at:

- [https://arc42.org/download](https://arc42.org/download)

## <svg aria-hidden="true" focusable="false" height="16" version="1.1" viewbox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg>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.

### <svg aria-hidden="true" focusable="false" height="16" version="1.1" viewbox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg>Good ressources over software documentation

- [https://bethaitman.com/posts/tld-2019/](https://bethaitman.com/posts/tld-2019/)
- [https://www.youtube.com/watch?v=R6zeikbTgVc](https://www.youtube.com/watch?v=R6zeikbTgVc)
- [https://leanpub.com/arc42inpractice](https://leanpub.com/arc42inpractice)
- [https://arc42.org/](https://arc42.org/)

(This article was posted to my blog at [https://larsroettig.dev](https://larsroettig.dev). You can [read it online by clicking here](https://larsroettig.dev/how-to-write-proper-software-documentation).)