documentation quadrants

Cooking analogy: teaching a kid to cook

Should be steps to complete an objective

How over what

Turns learners into users

Needs to be up to date!

Take as much time as the other three documentation quadrants categories put together

Learn by doing

Focus on getting them started, not necessarily doing it the "optimal" way

It needs to fucking work

Have immediate results

Make it repeatable

Concrete steps, not abstract concepts

Only explain what's currently necessary

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

Cooking analogy: books about analysis/the history/etc of cooking

Understanding oriented. Not any practical value.

Could also be called "discussions". Designed to be read at your leisure, no code required.

Typically not explicitly created, but instead are interspersed in other documentation (this is not the ideal way). They can be hard to create!

Are these architecture decision records?

Provide context, discuss alternatives. Don't instruct (that's a how-to guide) or provide technical references (that's a reference).

You don't need to know about this, but it could be nice to understand!

Cooking analogy: an article about a specific ingredient

Information oriented. Their only job is to describe.

Can contain examples, but shouldn't explain basic concepts (that's a tutorial) or how to do common tasks (that's a how-to guide). Should be "austere".

Basic descriptions of correct use is okay as long as it's focused on one thing, not an overall goal (unit test vs integration test).

Use the same structure as the code (should this be in-line and automatically generated?) (auto generated code isn't sufficient, they say, but maybe that's just documentation with no human input, not docblocks?)

Only describe. No flavor, only description! Examples are okay.