documentation-style

Documentation Style Review

Scope

Style conformance only: tone, voice, terminology, punctuation, Oxford comma, active versus passive voice, prohibited phrases, and formatting conventions.

Inputs

• Documentation file(s) under review.
• Normative style asset: references/doc-style-guide.md.
• Syntax-specific style guides (fetched at runtime):
  • MyST: https://raw.githubusercontent.com/canonical/sphinx-docs-starter-pack/refs/heads/main/docs/reference/myst-syntax-reference.md
  • reST: https://raw.githubusercontent.com/canonical/sphinx-docs-starter-pack/refs/heads/main/docs/reference/rst-syntax-reference.rst

Actions

1. Load style guides: Read references/doc-style-guide.md. Fetch the syntax-specific guide matching the file type (MyST for .md, reST for .rst).

2. Syntax compliance: Check headings, lists, code blocks, inline literals, and directives against the applicable syntax guide. Treat every instruction in the guide as mandatory; do not rely on a subset of rules.

3. Full style guide compliance: Read and apply all rules defined in references/doc-style-guide.md. Treat every instruction in the guide as mandatory; do not rely on a subset of rules.

4. Style guide citation: For every violation found, locate and quote the specific passage in references/doc-style-guide.md or the syntax-specific guide that supports the finding.

5. Fallback behaviour: If syntax guides cannot be fetched (offline or network blocked), continue the review using references/doc-style-guide.md and the syntax patterns already present in the documentation set.

   If references/doc-style-guide.md is unavailable, STOP the review and report that the style guide cannot be accessed.

6. Verification:

   Confirm the style review completed:

   • Style guides loaded (doc-style-guide.md and syntax-specific guide if available)
   • Syntax compliance checked against applicable guide
   • Style guide compliance checked against all rules in doc-style-guide.md
   • All violations cited with quoted passages from style guides