John Lancaster
55 lines
1.9 KiB
Markdown
55 lines
1.9 KiB
Markdown
# Documentation Quality Best Practices
|
|
|
|
Use this reference when writing or reviewing docs for clarity, correctness, and trust.
|
|
|
|
## Core Writing Principles
|
|
|
|
1. Write for a specific audience and task.
|
|
2. Lead with outcomes, not internal implementation details.
|
|
3. Keep concepts, tasks, and references distinct.
|
|
4. Make examples executable and verifiable.
|
|
5. Prefer precise language over marketing language.
|
|
|
|
Primary references:
|
|
- Diataxis: https://diataxis.fr/
|
|
- Divio documentation system: https://documentation.divio.com/
|
|
- Write the Docs guide: https://www.writethedocs.org/guide/
|
|
|
|
## Style and Readability
|
|
|
|
- Use consistent terminology and avoid synonym drift.
|
|
- Use short paragraphs and meaningful headings.
|
|
- Prefer active voice and imperative instructions for task pages.
|
|
- Add notes/warnings only for high-impact caveats.
|
|
|
|
Source links:
|
|
- Google developer style: https://developers.google.com/style
|
|
- Microsoft Writing Style Guide: https://learn.microsoft.com/style-guide/welcome/
|
|
- MDN writing guidelines: https://developer.mozilla.org/en-US/docs/MDN/Writing_guidelines
|
|
|
|
## Task Page Quality Pattern
|
|
|
|
Each task page should include:
|
|
|
|
1. Goal and scope.
|
|
2. Prerequisites (permissions, versions, environment).
|
|
3. Step-by-step procedure.
|
|
4. Expected result and verification command/output.
|
|
5. Common failure modes and recovery path.
|
|
6. Related links (concept, reference, troubleshooting).
|
|
|
|
## Quality Gates Before Publish
|
|
|
|
- Accuracy: commands and code examples are validated.
|
|
- Completeness: no critical missing steps.
|
|
- Discoverability: page is linked from at least one overview page.
|
|
- Freshness: version-specific notes and dates are present where needed.
|
|
- Accessibility: heading structure and link text are clear.
|
|
|
|
## Anti-Patterns
|
|
|
|
- Mixing conceptual explanation and long procedural flow in the same section without structure.
|
|
- Hiding prerequisites mid-page.
|
|
- Using screenshots as the only source of truth for commands.
|
|
- Publishing pages with no owner and no review cadence.
|