4 Types of Documentation Nobody Tells You About

Introduction

Good documentation should be easier to write and simpler to maintain.

What is documentation? In a narrow sense, it refers to explanatory texts related to programming, but in fact, many aspects of life can be considered documentation. Technical tutorials are a form of documentation, and recipes for cooking are also a form of documentation. Essentially, it refers to technical guides and reference materials. Mastering the way to write documentation means mastering how to better share knowledge so that it can be understood and used by others.

For Authors…

The biggest headache comes from the need to maintain documentation. Learning this structure can help them clearly understand how to write documentation and how to categorize it to assist themselves and their readers.

For Readers…

A clearer understanding of how to acquire knowledge effectively at different stages of learning.

Good Documentation: Four Types

I believe good documentation focuses on “the knowledge that current readers want to understand,” amplifying key points and removing other noise. Specifically, what types of readers might have these purposes?

• Learning-focused - Want to learn about a specific field
• Goal-focused - Want to solve a specific problem
• Information-focused - Want to acquire certain information
• Understanding-focused - Want to understand certain information

By observing the needs of readers and providing corresponding answers, we can summarize four key points to categorize documentation into several types:

• Tutorial - Emphasizing guidance and a sense of achievement
• How-To - Emphasizing goal achievement
• Reference - Emphasizing clear and complete information
• Explanation - Emphasizing understanding the context of thought

Tutorial

Tutorial documentation should emphasize guidance and a sense of achievement.

Tutorials allow readers to quickly get started and understand that they can achieve meaningful and rewarding things through learning. For example, teaching someone how to bake.

Ultimately, what that person learns is not important; what matters is that the tutorial is inspiring, engaging, and encourages further attempts, providing a good experience, which defines a good tutorial.

The process of teaching is interesting and overlooks technical details. Such articles must avoid explaining or discussing any abstract or overly complex concepts, usually focusing on specific fields and learning by doing, possessing a hands-on nature. Teaching is the most challenging type of documentation, and the best approach is for the instructor to interact as much as possible with the students (readers). Personally, I believe that at this stage, WHY is greater than HOW, meaning that “why learn X” is much more important than “how to learn X,” as it ignites the students’ motivation to learn.

• Learn by doing (creating stepping stones of knowledge)
• Start with simple tasks (it doesn’t have to be the best example, but it should be clear and simple enough for beginners to get started, rather than helping them reach the finish line)
• Achieve visible results immediately (ensure that each action is small but has visible effects)
• Provide minimal explanations to complete the tutorial (anything else will increase distraction and confusion)

How-To Guide

How-To documentation should focus on achieving a specific purpose.

How-To guides demonstrate the process of solving specific problems, allowing readers to understand that they can resolve an issue or achieve a goal through reading. For example, a recipe for cupcakes. If tutorials are entry guides for beginners, then How-To guides provide answers to questions posed by those with a certain knowledge background. Just like a pastry chef with a basic foundation can follow a recipe to make cupcakes.

The process should focus on achieving a specific goal, being goal-oriented. Such articles must also avoid explaining or discussing any abstract concepts; the only focus should be on how to quickly and simply achieve a desired outcome.

• Naming is important (the title of the documentation should clearly express a single, straightforward goal)
• Provide a series of clear steps (just like in tutorials)
• Emphasize results (must focus on achieving a specific goal)
• Do not explain concepts (if concepts are important, note them outside the documentation)
• Allow flexibility (permit different ways to achieve the same goal, giving students room for imagination and self-learning)

Reference

Reference documentation should emphasize understanding the context of thought.

References describe the functionality and interaction methods of things, allowing readers to understand that they can acquire desired information through reading. For example, Wikipedia. The process should be oriented towards describing detailed information, so having high consistency, tone, and precise grammar is important, being serious and to the point.

• Consistency in format and tone (like a dictionary)
• Clear descriptions (explanations, discussions, operations, guesses, and opinions can be distracting)

Explanation

Explanatory documents should prioritize clear and complete information.

Explanation clarifies, analyzes, and explains a specific topic, expanding the scope of understanding from different angles. For example, a book discussing the history of cooking. It approaches a problem from multiple sides, stepping back to gain a broader understanding of the whole picture. It provides perspectives on a topic for readers to expand their knowledge during their free time.

The process should provide sufficient context and omit steps and technical details, using multiple examples and alternative approaches instead.

• Provide context (explain the background conditions and history, such as design choices, technical limitations, historical factors)
• Discuss different aspects and choices (various viewpoints and analytical explanations)
• Avoid discussing technical details and steps (this type of content should be written in other types of documents)

Summary

This article summarizes the notes from Daniele Procida🔗 based on his talks at Write the Docs EU🔗 and PyCon Australia🔗. Although these concepts primarily summarize how developers should write documentation, I believe they can also be applied to various types of documents.

Sources

• The four kinds of documentation, and why you need to understand what they are🔗
• The documentation system🔗