Divio Documentation System

Credit to the Divio Documentation System https://documentation.divio.com/

​Allow beginner to get started

Must

Example

• Focus only on 1 way and its steps user need to take

• Minimum necessary explanation, link this

• Concrete steps and user should see result immediately

Writing Guide

TUTORIALS

Steps to install workstation

show how to solve a specific problem

Must

Example

• Focus on achieving practical goal

• Don't explain concepts, link this

• Can allow for slightly different ways of doing the same thing

Writing Guide

HOW-TO GUIDES

How to create a class based view

How to write a test case

describe the machinery

Must

Example

• Structure documentation around code

• Do nothing but describe, link explanations and discussions

• Provide examples to illustrate description when appropriate

Writing Guide

REFERENCE

API documentation

explain

Must

Example

• Give background & context

• Discuss alternatives & opinions

• Explanations

Writing Guide

EXPLANATION

Kafka concepts

Learning

​​Tutorial

Goal

​​How-To Guides

Information

​​Reference

Understanding

​​Explanation

Tutorials does not tell you what you will learn, the learning comes out of doing

How-to guides take the reader through required steps to solve a problem

Reference guides are technical descriptions of the machinery and how to operate it

Explanation or discussions broaden the documentation's coverage of a topic

You will be tempted to mix the content of each quadrant. Note that overbloating information might not help the reader to get to his/her purpose.

Divio Documentation System

Credit to the Divio Documentation System https://documentation.divio.com/