Documentation System

Documentation System

Use Divio's documentation model: there is no single thing called documentation. There are four modes, each with one job:

Keep modes separate. Mixing modes is usually the defect.

Operating workflow

1. Identify reader state.
   • Newcomer learning? Tutorial.
   • User with a concrete goal? How-to.
   • User looking up API/CLI/config facts? Reference.
   • User asking why, context, design, tradeoffs? Explanation.
2. Pick exactly one primary mode per document.
3. Move off-mode material elsewhere or convert it into links.
4. Write in the mode's shape.
5. Review with the quadrant checklist.
6. If auditing existing docs, produce a split/merge plan before rewriting.

Classification rules

Ask:

• Does title start with "How to ..." and answer a specific problem? how-to.
• Does it teach a beginner through a safe, meaningful first project chosen by the author? tutorial.
• Is it structured like code/API/CLI/config and only describes facts? reference.
• Does it discuss concepts, background, reasons, alternatives, or tradeoffs? explanation.

If more than one is true, classify by dominant user need, then extract the rest.

Mode rules

Tutorial

Use when the reader needs guided first success.

Must:

• Be a lesson, not a manual.
• Take responsibility for what the learner does and in what order.
• Use concrete steps with visible results quickly.
• Keep the path robust and repeatable.
• Prefer a meaningful small accomplishment over completeness.
• Include only minimum explanation needed to finish.
• Link to explanations/reference instead of embedding them.

Avoid:

• Detours, options, edge cases, abstractions, best-practice debates.
• Assuming expert judgment.
• Steps not tested end-to-end.

Template:

# Build/Do <small meaningful thing>

In this tutorial, you will <concrete outcome>.

## Prerequisites
- <minimal known-good setup>

## 1. <First visible step>
<exact action>

Expected result: <what they should see>

## 2. <Next step>
...

## What you achieved
- <concrete accomplishments>

## Next steps
- <link to how-to/reference/explanation>

How-to guide

Use when the reader has a specific goal and enough background to ask for it.

Must:

• Answer "How do I ...?"
• Start at a reasonable point, not from absolute zero.
• Provide ordered steps toward one practical result.
• Focus on outcome, not teaching.
• Allow limited adaptation for common variants.
• Leave out unrelated details.
• Link to explanation/reference for context and full facts.

Avoid:

• Beginner teaching.
• Conceptual essays.
• Exhaustive option catalogues.
• Vague titles like "Authentication" when "How to enable LDAP authentication" fits.

Template:

# How to <achieve specific result>

Use this guide when <situation>.

## Prerequisites
- <assumed knowledge/setup>

## Steps
1. <action>
2. <action>
3. <action>

## Verify
<expected result/check>

## Variations
- If <case>, do <adjustment>.

## Related
- <reference/explanation links>

Reference

Use when the reader needs accurate lookup information about machinery.

Must:

• Describe only.
• Mirror code/API/CLI/config structure where possible.
• Be complete, accurate, and consistent.
• Use stable headings and repeated field formats.
• Include examples only to illustrate usage.
• Record constraints, defaults, types, parameters, errors, side effects, compatibility.

Avoid:

• Teaching journeys.
• Task recipes beyond basic invocation/use.
• Background essays or rationale.
• Opinion unless clearly part of semantics/constraints.

Template:

# <API/command/module/config name>

Brief factual description.

## Signature / Syntax
`<exact form>`

## Parameters / Options / Fields
| Name | Type | Required | Default | Description |
|---|---:|---:|---:|---|

## Returns / Output
<facts>

## Behavior
<rules, constraints, side effects>

## Errors
| Error | Cause | Notes |
|---|---|---|

## Examples
<minimal illustrative examples>

## See also
- <how-to/explanation links>

Explanation

Use when the reader needs context, reasons, or a bigger mental model.

Must:

• Clarify and illuminate a topic.
• Discuss why things are as they are.
• Compare alternatives and tradeoffs.
• Include background, history, constraints, design rationale.
• Be readable away from code/task pressure.

Avoid:

• Ordered task instructions.
• API catalogues.
• Pretending an opinion is a fact.
• Making the reader hunt through essays for operational steps.

Template:

# Understanding <topic>

<Short framing: why this topic matters.>

## Context
<background and problem space>

## Mental model
<core concepts and relationships>

## Why it works this way
<constraints, decisions, history>

## Alternatives and tradeoffs
<option A vs B, when each matters>

## Consequences
<practical implications without step-by-step instructions>

## Related
- <tutorial/how-to/reference links>

Audit checklist

For each document, report:

## Documentation audit: <doc>

Primary mode: tutorial | how-to | reference | explanation
Reader need: <need>
Pass/fail: <summary>

### Off-mode material
- <section>: belongs in <mode> because <reason>

### Missing material
- <needed doc/section>: <mode> because <reason>

### Proposed structure
- <keep>
- <move/split>
- <rewrite>

### Immediate edits
1. <smallest valuable edit>
2. <next edit>

Writing output contract

When asked to write docs:

1. State selected mode in one line.
2. Write the doc in that mode.
3. Add "Related docs" links/stubs for displaced modes.
4. Do not mix modes to be helpful. Link instead.

When asked to plan docs IA:

docs/
  tutorials/
    <lesson>.md
  how-to/
    how-to-<goal>.md
  reference/
    <api-or-component>.md
  explanation/
    <concept>.md

Smaller projects may omit empty quadrants, but keep labels and intent clear when material exists.

Review gates

Reject or revise if:

• Tutorial has untested or invisible-result steps.
• How-to lacks a specific goal.
• Reference explains rationale instead of describing facts.
• Explanation contains command sequences users must follow.
• One document tries to be all four modes.

Use this final note when helpful: "This content is useful, but belongs in , not here. Link it."

Source: barlevalon/skills — distributed by TomeVault.