Technical content

There are at least four types of documentation (the link includes a video talk on the types). They all focus on different things:

• Tutorials: teaching the basics to people without previous experience
• How-to guides: helping people with some knowledge complete a specific task
• Reference: describing information in detail
• Explanations: helping people understand the reasons behind the project

Each of these types has different goals. To decide which to write, it helps to know who you’re writing for.

For each type, you want to pick a specific topic with a specific goal and write only about that topic. Use links to give people access to additional context and related topics.

When you know the specific topic, give it a short title to make it clear what the document contains. For most types, the title should emphasize the action (“Making a reservation”, “Deploying your app to Kubernetes”).

How-to guides should not include “How to” in the title. Explanations can (but don’t have to) include actions emphasizing their type (such as “Understanding”) or nouns describing the topic (“Baggage overview”).

For each type, the document should include a brief introduction describing its purpose. It should be clear who the doc is written for and what they should get out of reading it.

Always include clear headings to structure your document into clear sections.

The introduction should include why the given product or service is important.

Then the tutorial should guide the reader through an ordered series of steps that teaches them the basics of how to accomplish something.

The introduction should make it clear what users can accomplish with the guide and why they’d want to do so.

The guide should continue with clear, ordered steps for accomplishing the task. Put any information that’s not immediately useful to accomplishing the task elsewhere, such as in a reference guide, and add a link to it..

The introduction should explain what information is included in the guide and why it might be useful.

The rest of the guide should be information that’s clearly structured without many details on why or how to accomplish something. Include links to specific how-to guides when relevant.

The introduction should include why the reader should be interested in learning more about the given topic.

It should then continue with more general discussion, taking a higher-level perspective on the topic. Any technical information should be placed in a separate reference guide and linked to. Any tasks should be given separate how-to guides and linked to.