zensical-docs skills started

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

@@ -0,0 +1,54 @@
+# 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.