prompts/docs/skills/zensical-docs/references/documentation-quality.md

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.