What nobody tells you about documentation (by Daniele Procida)

• Original: https://www.youtube.com/watch?v=t4vKPhjcMZg
• See also: https://www.divio.com/en/blog/documentation/

There are for "quadrants" of the documentation that have a fairly non-overlapping sets of qualities. It's better to clearly separate them and not let them mix.

| | Good for study | Good for work | |---------------------------|----------------|----------------| | Practical steps | Tutorials | How-to guides | | Theoretical knowledge | Discussions | Reference docs |

Those parts often want to get blurred, but the technical writer should resist this tendency and keep them clearly separated.

Tutorials

Lessons that take the reader by the hand through a series of steps to complete a project.

• Concrete, focus on a specific example,
• Start from scratch,
• Less explanation, more action, learning by doing,
• Don't need flexibility, just easy steps that get you to the goal,
• Fool-proof, should work anywhere,
• We want to inspire confidence and give immediate sense of achievement.

HowTo guides

Take the reader through the steps to solve a common problem.

• A series of steps,
• Focus on the goal,
• No unnecessary explanation,
• Some flexibility,
• Naming is important "How to create a shared view" > "Shared views".

Reference documentation

Technical description of the machinery and how to operate it.

• Structure should mirror the structure of the code,
• Consistent style,
• Describe what's there, don't give instructions,
• Must be accurate and up to date.

Discussion

Explanations that clarify and illuminate a particular topic.

• Give context,
• Explain why,
• Give examples, alternative approaches,
• Make connections,
• No instruction or technical description.