Writing technical documentation

What makes a good technical documentation?

Diataxis: A systematic approach to technical documentation authoring.

• tutorials
• how-to guides
• reference
• explanation

Tutorials

Introduction

• This tutorial discusses…
• This tutorial walks you through…
• In this tutorial you learn how to…
• X is a feature Y that allows…
• X is a service that enables you to…
• If you have X, you might want Y to…
• An example use case is a…
• For the purpose of illustration…
• In this article, we will be primarily dealing with
• first one of a set of blogposts targeting embedded systems hardening

Example

• A minimal C++ class declaration might read…

Overview

In this tutorial you perform the following tasks:

• Create X and add Y
• Perform X
• Check the results of X
• Use X to Y.

Prerequisites

• Before beginning this tutorial…
• You need X version Y or later on your development machine…
• You can download X here…
• You can verify your installation with…
• Make sure, that…

Create…

• Run X command to…
• Select X on the left pane then select…
• Enter X in Y…
• Add the following code to…
• Complete the fields as follows…

Perform…

Clean up…

Next steps

• In this tutorial, you learned how to…
• Advance to the next tutorial about X to…
• You can find more information on…
• Lastly, here are some additional resources you may find useful…