Product Documentation Style Guide

This style guide defines how to write, structure, review, and maintain product documentation so content is clear, consistent, and useful.

• New users onboarding to the product
• Existing users completing operational tasks
• Internal teams (support, success, implementation, engineering)

1. Task-first over feature-first.
2. Clarity over completeness.
3. Consistency over creativity.
4. Actionable guidance over conceptual explanation.
5. Keep pages skimmable, then expandable.

• Use direct, plain language.
• Use second person for instructions (“you”).
• Use active voice.
• Be concise but specific.

Good:

• “Open Project Settings and select Data Retention.”

Avoid:

• “Data retention can then be configured by users in settings.”

Use this order unless there is a strong reason not to.

1. Purpose

• One short paragraph describing the outcome.

2. When to Use

• Bullet list of scenarios.

3. Prerequisites

• Permissions, inputs, dependencies.

4. Steps

• Numbered sequence with one action per step.

5. Expected Result

• What success looks like.

6. Troubleshooting

• Common errors, cause, and resolution.

7. Related Docs

• Next-step links and adjacent tasks.

• Keep introductions to 2-4 sentences.
• Keep paragraphs to 2-4 lines.
• Prefer numbered steps for procedures.
• Use bullets for options and conditions.
• Use one idea per sentence where possible.
• Avoid internal jargon without definition.

• Use one term for one concept across all pages.
• If a UI label exists, match it exactly.
• Capitalize product feature names consistently.
• Avoid synonyms for core objects (for example, do not alternate between “job” and “task” unless they are different entities).

• One H1 per page.
• Use H2 for primary sections.
• Use H3 only when needed.
• Do not skip heading levels.
• Use descriptive headings (“Configure Retention Rules”) not vague headings (“Configuration”).

• Start each step with a verb.
• Include exact UI path when relevant.
• Include expected visible confirmation for key actions.
• Include branch instructions for conditional flows.

Example:

1. Open Settings.
2. Select Security.
3. Turn on Enforce MFA.
4. Select Save.
5. Confirm the banner shows “MFA policy updated”.

• Include copy/paste examples for inputs when possible.
• Show expected output after example commands or configuration.
• Label placeholders clearly.

Example:

retention_days: 30
auto_archive: true

Use callouts intentionally and sparingly.

• note: supplemental context or helpful tips.
• warning: high-risk actions or irreversible outcomes.
• breaking-change: behavior changes requiring user action.
• migration: upgrade path guidance.
• security: security-sensitive instructions.

Example:

  

  
Deleting this configuration removes all associated historical data.

Rules:

• Keep callout body short (2-6 lines).
• Put required action in the first sentence.
• Do not stack multiple warning-level callouts back-to-back.

• Prefer descriptive link text (“Configure report filters”), not “click here”.
• Add a “Related Docs” section at the end of every task page.
• Add “Next step” links when a workflow continues.
• Avoid dead-end pages.

• Include screenshots only when text is insufficient.
• Capture current UI only.
• Crop to the relevant region.
• Avoid including sensitive data.
• Add short caption with intent (what to notice).

• Use clear heading hierarchy.
• Do not rely on color alone for meaning.
• Use meaningful link text.
• Keep sentence complexity low.
• Use tables only when row/column comparison is necessary.

Required page metadata:

---
title: Example Page
weight: 10
---

Optional metadata:

---
docType: guide
---

Rules:

• Use docType: guide for procedural pages.
• Use docType: reference for specification/reference pages.
• Keep title concise and outcome-focused.

Use guide when the user needs to complete a task. Use reference when the user needs definitions, limits, field details, or lookup data.

Guide characteristics:

• procedural
• step-based
• includes prerequisites and outcomes

Reference characteristics:

• structured data
• definitions and constraints
• minimal narrative

Each release note should include:

• What changed
• Who is affected
• Action required
• Deadline (if applicable)
• Migration path (if applicable)

If a change is breaking, include a breaking-change callout near the top.

Before publishing, confirm:

• Title clearly describes the outcome.
• Template sections are present and complete.
• Steps are accurate and tested.
• Troubleshooting is included for risky tasks.
• Links work and point to current pages.
• Terminology is consistent.
• Callouts are used correctly.
• Spelling and grammar are clean.

• Assign one owner per section.
• Add review cadence (monthly or quarterly depending on change rate).
• Prioritize updates based on support volume and usage.
• Track stale pages and refresh dates.

• P0 workflow pages: validate monthly.
• P1 pages: validate quarterly.
• P2 pages: validate twice per year.

1. Draft update.
2. Technical review by SME.
3. Editorial review against this guide.
4. Publish.
5. Monitor feedback and support impact.

Do:

• Write for user outcomes.
• Keep steps concrete.
• Provide recovery guidance.
• Link to next tasks.

Do not:

• Write long feature history before instructions.
• Use ambiguous terms.
• Publish pages without validation.
• Leave procedural pages without expected results.