Write documentation that flows
Structure long-form articles with headings, tables, callouts, and focused examples.
Start with the outcome
Put the reader's desired outcome in the first paragraph. Explain the prerequisites before asking them to change a setting. Every instruction should make the next action clear.
Give the page a rhythm
Use level-two headings for major sections and level-three headings for supporting details. The table of contents is generated from those headings. Keep heading names specific enough to make sense without the surrounding paragraph.
Write for scanning
Readers often arrive from a search result rather than the beginning of a guide. Each section should provide enough context to be useful on its own. Use short paragraphs without turning every sentence into a bullet.
Preserve technical precision
Use inline code for identifiers such as project_id. Show a complete example before introducing optional variations. Distinguish a placeholder from a literal value.
Compare options
| Option | Use it for | Default |
|---|---|---|
| Preview | Checking layout before publishing | Enabled |
| Draft | Work that readers should not see | Disabled |
| Locale | The language of this article | English |
Explain important constraints
Editing longer articles
Long pages should remain comfortable to read on a phone. This template limits the reading width while letting tables and code scroll locally. Test real content, including long identifiers and Japanese paragraphs, before publishing.
Use meaningful links
Link text should describe its destination. Prefer getting started to generic link labels. This template renders text rather than executing embedded HTML in the Markdown field.
Supported content
- Paragraphs, bold text, inline code, and links
- Level-two and level-three headings
- Ordered and unordered lists
- Fenced code with a language label and copy button
- Tables with a header row
- Blockquotes for callouts
Raw HTML, MDX, nested lists, and automatic syntax highlighting are outside the first-release scope.