| name | docs-style |
| description | Automatically applies when drafting or revising documentation to enforce repository voice, clarity, and navigation patterns. |
| category | documentation |
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.
