how-to guide documentation quadrant

Cooking analogy: a recipe

Solve a real-world problem

Not a tutorial! Tutorials are you teaching a beginner what they need to know; how to guides answer questions someone experienced could ask.

Assume basic knowledge

Provide a series of steps (order matters). Don't have to start at the beginning, just a "reasonable" starting point.

Focus on the result (the goal they're achieving)

Solve one problem (additional problems should be solved in other guides).

Don't explain concepts: that's for other documentation quadrants. Link to them.

Have flexibility: so they could use the steps for a similar but slightly different problem.

Be practical, not complete: it's okay to leave things out.

Name the guide something that explicitly says what it's for.

Think of it as an integration test, as opposed to the reference's unit test