[Product name] documentation plan

Plan the whole docs set here: fill in the docs map first, then copy the outline for each page you write. Replace the blue placeholders and delete the grey notes as you go.

Product	[Product name and version]
Docs owner	[Name]
Readers	[Admins, end users, developers]
Published at	[Docs site address or folder]
Last reviewed	[Date]

Readers and the jobs they come to do

Collect jobs from support tickets, onboarding calls, help-center searches and the product's main screens. Each job becomes a page.

Reader	Comes to	Page that answers it
[Reader]	[Job, written as a task]	[Page title]
[Reader]	[Job, written as a task]	[Page title]
[Reader]	[Job, written as a task]	[Page title]

Docs map

One row per page. Every page gets an owner; a page without one tends to go out of date first.

Page	Type	Reader	Owner	Status
[Product] documentation	Overview	[Everyone]	[Name]	[Draft]
Quickstart: [first result]	Tutorial	[New users]	[Name]	[Draft]
Tutorial: [project]	Tutorial	[Reader]	[Name]	[Planned]
How to [task]	How-to	[Reader]	[Name]	[Planned]
How to [task]	How-to	[Reader]	[Name]	[Planned]
How [concept] works	Explanation	[Reader]	[Name]	[Planned]
[Area] reference	Reference	[Reader]	[Name]	[Planned]
Troubleshooting [area]	How-to	[Everyone]	[Name]	[Planned]
Release notes	Reference	[Everyone]	[Name]	[Ongoing]

One page, one job. Apart from the overview, every page is one of four kinds: a tutorial (learning by doing), a how-to guide (one task), reference (facts to look up) or explanation (how and why). If a page starts doing two jobs, split it and link the halves.

Overview page

What it is: [one sentence on what the product does and who it is for]
What you can do: [three to five tasks, each linking to a how-to guide]
Start here: [link to the quickstart]
How the docs are organized: [a short list of the sections]
Getting help: [where to ask, and what to include]

Quickstart

At the end you will have: [the first real result, and roughly how long it takes]
Before you start: [account, permissions or files you need]

[First action, with the exact label on the screen] You should see: [what changes]
[Second action] You should see: [what changes]
[Third action] You should see: [the first result]

Next steps: [link to a tutorial] and [link to a how-to guide]

See example quickstart steps

Select Add shift, choose Monday 9:00–17:00 and assign it to yourself. You should see the shift on the calendar in gray, marked Draft.
Repeat for two more people on your team.
Select Publish week. You should see the shifts turn blue, and each person gets an email with their shifts.

From Roster, an invented scheduling app. Exact button names, and a result after every step.

Tutorial

What you will build: [the project, in one sentence]
What you will learn: [two or three skills]
Prerequisites: [what the reader must have done first, such as the quickstart]
Sections: [short sections, each ending with a checkpoint]
Recap and next: [what the reader can do now, and where to go]

A tutorial makes the choices for the reader. Leave options and edge cases to how-to guides and reference.

How-to guide

Title: How to [task]
When you would do this: [one or two sentences]
Before you start: [permissions, settings, data]
Steps: [numbered, with the exact labels on the screen]
Result: [what the reader has when they finish]
Related tasks: [links]

Concept page

The idea: [one paragraph]
How it works: [plain explanation; a diagram if a picture is clearer]
Why it works this way: [the design reasons and the trade-offs]
Related: [reference pages and how-to guides that use it]

Reference page

One page per group of settings, endpoint, command or error list. The same table on every page, no advice.

Name	Type	Default	What it does	Example
[Setting name]	[Type]	[Default]	[Behavior, including what it doesn't do]	[Example value]
[Setting name]	[Type]	[Default]	[Behavior, including what it doesn't do]	[Example value]

See an example reference row

Minimum rest between shifts · hours · default 11 · Roster warns the admin when a new shift starts less than this many hours after the same person's previous shift ends. It doesn't block the shift.

Troubleshooting page

Start every entry from what the reader sees, quoted exactly. Put the most common problems first.

What you see	Why it happens	How to fix it
[Exact message or symptom]	[Cause]	[Steps to fix it]
[Exact message or symptom]	[Cause]	[Steps to fix it]

Release notes

Version and date: [1.0, date]
Highlights: [one or two sentences]
New, improved, fixed: [what changed for the user]
Breaking changes: [what changes and exactly what to do about it]
Pages updated: [links to every docs page this release changed]

Before you publish

Every page in the docs map has an owner and a status
Someone new followed the quickstart without help
Button labels, settings and error messages match the product exactly
Every how-to guide states its result
Release notes link to the pages they changed
Every page shows a last-reviewed date