The Four Types of Software Documentation

I stumbled on this model of software documentation that states there are four kinds. Tutorials, how-to’s, explanations, and reference documentation. Poking around the knative documentation, this model was revelatory to see it described via this simplistic model. For a long time, I struggled to coach my teams on what they should document and what they should not. My previous heuristic was a mix of rules I’ve learned over time but never documented myself. Is it changing? Will it change within a month? Skip documenting it. Will it remain true? Referring to a specific line might add confusion if someone isn’t aware you made this reference. Will this only confuse users? Are you inviting unnecessary bewilderment?

While those are helpful questions to ask, it is not something that comes up often in conversation. This model is much more direct and approachable in keeping a team aligned on what is worth producing for users.

The Four Types of Documentation

I am thankful to Daniele Procida for creating this mental model of documentation. It cuts to what is valuable for users and helps people avoid learning on their own what doesn’t work. Your users are people that want to complete their tasks via your software. They do not need philosophical musings, aspirational poetry, or first drafts. They want valuable content that informs what they should do and what they should avoid doing with your software.

Tutorials

A tutorial is a written narrative on how to complete a task using the software. With video as ubiquitous as it is, it may not require thorough written tutorials. It is a big world out there. You might have a user that prefers one medium over another. Or they only want to know how to complete one portion of a task. Tutorials are super valuable, but they are expensive to maintain and laborious to create. Videos and animated images can help overcome some of the gaps of working with disparate technology concepts. Or a lot of the container-based systems like katacoda/repl.it makes it easier to replicate a scenario.

How-To Guides

How-tos are about guiding someone to solve a problem they know how to articulate or search via a keyword. You are offering a solution to that problem via some documentation. These are great for common challenges that require a workaround. These articles should be narrow and focused on simple topics. Daniel provides examples of successful how-tos.

Reference

Reference material is written plainly about what is available and how to work with it. This information is spartan compared to tutorials. What do the APIs do, how do you interact with them, and what are the limitations? These should be described simply as what inputs and outputs occur in typical scenarios.

Explanation

An explanation educates users on the place and situation of technology and why it is in use and available. The first three types of documentation are ones I want my team to nurture and prune over time. Explanations, in the case of Kubernetes, are better left to the broader software industry to cover. Writing is a distinct skill from general software development. It is a lot to ask for your engineers to be expert writers. If you have people that can do write, great! It might be worthwhile to leverage outside resources. For example, I could ask my team to focus on explanations and videos around why Kubernetes and CICD are great. It would be a better use of the technical trainer’s time or someone else that can gather, organize, and synthesize information and knowledge available from quick google searches. Even better pay for an external trainer to come in if this is a large initiative anyhow. You’ll save a ton of everyone’s time and energy trying to assemble their learning.

Conclusion

Documentation is something you need to maintain and review over time. It can also be the life or death of a technical product. I’ve found with Dev.Lab that the early adopter developers are more comfortable reading my tutorials and videos before reaching out for assistance.

• Use the four types of documentation as a starting place for your next software project’s documentation.
• Consider focusing on tutorials over other types foremost.
• Collect feedback and input on what documentation is working well and what needs to be eliminated.

What do you think? Is documentation worthwhile? When is it not worthwhile? Where does this break down?