Documentation Style Guide

Trigger Keywords: documentation, doc update, README, guide, tutorial, changelog, ADR, design doc, style, tone, voice, copy edit

Agent Integration: Used by

spec-writer

,

technical-writer

, and

requirements-analyst

when delivering reader-facing content.

Voice and Clarity

• Prefer concise, direct sentences; remove filler and marketing language.
• Use active voice and parallel sentence structures.
• Lead with outcomes, then supporting details.
• Keep language project-agnostic so the plugin works in any Python project.

Structure and Navigation

• Start with a short purpose/summary before detailed sections.
• Use consistent heading levels and ordered sections; avoid nested lists where possible.
• Include quick-scannable bullets and tables for comparisons or options.
• Add cross-references to related specs, tasks, and reference docs.

Formatting Patterns

• Use fenced code blocks with language tags for examples.
• Keep line wrapping consistent; avoid trailing whitespace.
• Use bold keywords sparingly for emphasis; prefer headings + bullets.
• For checklists, use ordered steps when sequence matters, unordered when it does not.

Quality Checklist

• ✅ Audience and scope identified at the top.
• ✅ Clear outcomes and verification steps included.
• ✅ Terminology consistent across the document.
• ✅ Links/paths are workspace-relative (no IDE/URL schemes).
• ❌ Avoid passive voice that hides ownership or action.
• ❌ Avoid giant paragraphs; break into digestible chunks.