Writing pages

Docs pages should be easy to scan, easy to link, and easy to maintain. Start with a clear title, a short description, and headings that match the tasks readers came to complete.

Page anatomy#

A consistent page structure makes docs easier to scan and easier to maintain.

• Frontmatter for metadata.
• Short introduction text.
• Main sections with ##.
• Supporting sections with ###.
• Practical examples readers can copy.
• Links to the next task when a page is part of a workflow.

Opening paragraph#

The first paragraph should explain why the page exists. Avoid repeating the title.

Section headings#

Headings should describe the job readers are trying to complete. A table of contents is only useful when headings are concrete.

Writing style#

Use direct verbs, short paragraphs, and concrete examples. Avoid explaining internal implementation unless the reader must change it.

Good page pattern#

Start with context, then show the workflow, then add reference details. This pattern works for setup guides, feature docs, and publishing checklists.

Scannability#

Readers often open docs while trying to complete another task. Make sure headings, lists, and examples help them find the right section quickly.

Strong first sentences#

Start each section with a sentence that explains the point of the section. Avoid dropping directly into a list or code block without context.

Useful subheadings#

Use ### headings when a section has multiple decisions, examples, or review notes. This makes the table of contents more useful on long pages.

Revision pass#

After drafting a page, read only the headings from top to bottom. The outline should tell a coherent story before the body copy is considered finished.

Cut repeated context#

If two sections start with the same explanation, keep the stronger version and make the other section more specific.