Skip to main content
A good navigation structure gets readers to the right page. The page still has to help them finish the job. Readers rarely start at the top and study every sentence. They scan headings, code blocks, lists, and visual cues until they find the section that matches their immediate question. Build pages for that behavior.

​
Give each page one clear goal

Before writing, finish this sentence: “After reading this page, the reader can ___.” If the answer contains several unrelated verbs, split the page. “Install the SDK, understand our architecture, and troubleshoot webhooks” is at least three goals. Match the page structure to its content type:
  • A tutorial guides a learner through a complete experience.
  • A how-to guide starts with a known goal and provides the shortest reliable path.
  • Reference content makes facts easy to locate and compare.
  • An explanation builds understanding through context and relationships.

​
Put prerequisites before instructions

Tell readers what they need before they start working on a task.
  • Required accounts, roles, or permissions
  • Software and supported versions
  • Values they need to collect
  • Setup they should have completed elsewhere
Link directly to prerequisite instructions. Don’t make readers discover halfway through a procedure that they lack access or need another tool.

​
Write headings that tell the story

A reader should understand the page’s shape by scanning its headings alone. Use headings that name a task, decision, or question:
  • “Generate an API key” instead of “API keys”
  • “Choose a deployment region” instead of “Options”
  • “Fix a 401 response” instead of “Troubleshooting”
Keep the hierarchy meaningful. Use ## for the main sections and ### for subsections within them. Don’t skip levels only to change the visual size.

​
Introduce examples before showing them

Before a code block, tell readers what it does, where it belongs, and what they may need to replace. Afterward, state the expected result when it isn’t obvious.
For this example, the surrounding page should explain where to find the API key and what a successful response looks like. The code shouldn’t carry the full teaching burden.

​
Put help near the failure point

Don’t collect every warning and troubleshooting note at the bottom of a long guide. If step three commonly fails because of permissions, mention the required permission before step three and link to the relevant fix there. Keep broad troubleshooting pages for symptoms that can occur in many workflows. Keep task-specific recovery close to the task.

​
End with proof and direction

Tell readers how to confirm that they succeeded. A useful verification is observable.
  • A command returns a specific value
  • A new status appears in the dashboard
  • An API request returns 200 OK
  • The published page appears at a known URL
Then tell them what comes next—if there is a meaningful next step. Don’t add navigation only to fill the bottom of the page.

​
Review the page as a stranger

Before publishing, check:
  • Can someone understand the goal from the title and description?
  • Are all prerequisites visible before the first action?
  • Do the headings make sense without the paragraphs beneath them?
  • Can a reader tell what to copy, change, and expect from each example?
  • Is help placed near the step that can fail?
  • Does the page say how to verify success?
Next up: Design navigation for your users — Connect well-structured pages into paths that match user goals.