Writing these docs · 02
Page types
The 6 kinds of page these docs have, and how to start one from its template.
Every page is one of 6 types, and its front matter says which (type: guide). The type sets the page's shape, so a reader knows what they'll find before they start reading. The checks hold each page to its type's shape.
The types
| Type | What it's for | It must have |
|---|---|---|
overview | A product's or section's front page: what it is and how its parts fit. | The only type with an illustration |
quickstart | The shortest path to a first result, one per product. | Before you start and Steps |
guide | One task, start to finish. | Steps or a numbered list |
concept | How something works and why. | How it works |
reference | Settings, limits, fields and formats to look up. | No steps |
troubleshooting | Problems, each under a heading that names the symptom. | A cause and a fix for each |
Every type ends with What's next and 2 to 4 links. When a page wants to be 2 types, it's usually 2 pages: a concept that explains the model, and a guide that links to it.
Start a page
Run npm run new with the type, the page's path under content/docs and its title:
npm run new -- guide argon/journeys/create-a-journey "Create a journey"It copies the type's template from templates/, adds the page to its folder's meta.json and creates any folders on the way. Each ✎ in the page marks something to write; npm test fails until none are left.
What's next
- How a page is built: where pages live and the voice they're written in.
- Components: callouts, steps, tabs, cards, screenshots and code blocks.