John Lancaster
55 lines
2.0 KiB
Markdown
55 lines
2.0 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.
|
|
|
|
!!! info "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.
|
|
|
|
!!! info "Style sources"
|
|
- [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.
|