Write with clarity

Give every page a purpose, keep the structure predictable and help readers find the detail they need.

Start with the outcome

Open with the question the page answers. Explain the result before adding background so readers can quickly decide whether they are in the right place.

Make the structure visible

Use short sections, descriptive headings and concrete examples. Keep prerequisites near the beginning and explain unfamiliar terms where they first appear.

• Use active verbs for instructions.
• Keep a consistent name for each concept.
• Split long procedures into smaller tasks.
• Use links when another page already explains the background.

Read it as a newcomer

Check each instruction without relying on context from another conversation. Make the page useful on its own.