Skip to content
Hungrimind Handbook

How to Write Docs

Docs are used to inform and educate users about the product. To be the very best docs they must have a consistent and easy to understand structure and be well written. Depending on the type of document they are. These should follow our brand personality.

Diataxis Framework

This is a technical documentation framework created by Daniele Procida who is the Director of Engineering at Canonical. This framework has been the industry standard across many of the biggest projects including Stripe, Ubuntu, and Kubernetes docs.

The core concept of this framework is that there are 4 types of documents:

  • Tutorials
  • How-to Guides
  • Explanations
  • Reference

Each of these documents have a different structure and purpose.

How-to Guides (we just call these “Guides”)

How-to guides are directions that guide the reader through a problem or towards a result. How-to guides are goal-oriented.

Guides are about a specific topic related to the product, what it is and how to use it. These are step-by-step guides when necessary which include deep explanations, screenshots, and code examples.

These are the most important document. The rest are almost optional and extras. These are what you think of when you think of “docs”

Examples

  • Managing Multiple Languages
  • Accessing Global State
  • Managing Certificates
  • Monitoring Your Cluster

Soft rule: a title should be 2-4 words.

Structure of the Document

  1. What and Why?
  2. Setup/Prerequisites (if needed)
  3. Step-by-Step (How?)

Tutorials

A tutorial is an experience that takes place under the guidance of a tutor. A tutorial is always learning-oriented.

The difference between guides and tutorials is that they take you through an entire story, which can use multiple parts of a product and the purpose is learning.

Examples

  • Quickstart
  • Guided Tour
  • Building a Workout App using Flutter Kit
  • Adding Payments to Your App (eventually this might turn into a guide once it’s part of the product, but now it would need to touch many different parts if we’re walking them through manually)
  • Scaling Your Cluster Horizontally

Structure of the Document

  1. What and Why?
  2. Setup/Prerequisites (if needed, and default should be to include them in the Step-by-Step)
  3. Step-by-Step (How?)

Explanations (we call these “Concepts”)

Explanation is a discursive treatment of a subject, that permits reflection. Explanation is understanding-oriented.

The difference between this and Guides and Tutorials is that it’s a high level overview of a concept. It doesn’t need to walk Step-by-Step (unless helpful for small parts). Currently we have these included directly in the guides for specific topics, and only add documents here when it is a more general concept that doesn’t have a Step-by-Step walkthrough associated to it.

Examples

  • MVVM Architecture
  • How Kubernetes Works

Structure of the Document

  1. What and Why?

Reference

Reference guides are technical descriptions of the machinery and how to operate it. Reference material is information-oriented.

A list of all the commands and options available in the product.

Examples

  • Utilities
  • CLI Commands

Structure of the Document

  1. What and Why?
  2. List (with description for each)

How We Structure the Docs

  • Get Started
    • Introduction - Introduce the product, what they get
    • Guided Tour (Tutorial) - Should touch all the parts people need to feel like they know the core parts of the product
  • Guides
    • Documents separated per topic
  • Concepts
    • Documents separated per topic
  • Tutorials
    • Documents separated per tutorials
  • Reference
    • Documents separate per reference type
    • Changelog