BMAD-METHOD/docs/documentation-standards/style-guide.md

BMAD Documentation Style Guide

Overview

This style guide establishes consistent standards for all BMAD Method documentation. Following these guidelines ensures our documentation is professional, accessible, and maintainable across all personas and use cases.

Document Structure

Headers and Sections

• Use ATX-style headers with a space after the hash marks (#)
• Maintain proper header hierarchy (H1 > H2 > H3)
• Include only one H1 (#) per document
• Keep headers concise (3-7 words)
• Use sentence case for headers

Formatting

• Bold for emphasis and UI elements
• Italics for introducing new terms
• Code formatting for code snippets, commands, and file paths

• Blockquotes for important notes or quotes

• Horizontal rules (---) to separate major sections

Writing Style

Voice and Tone

• Use active voice
• Write in present tense
• Be concise and direct
• Use second person ("you") to address the reader
• Maintain a professional, helpful tone

Grammar and Mechanics

• Use Oxford commas
• Spell out numbers one through nine, use numerals for 10+
• Use sentence case for titles and headings
• Avoid contractions in formal documentation
• Maintain consistent terminology throughout

Code Examples

• Include language identifier with code blocks
• Keep examples concise and focused
• Include comments for complex code
• Use placeholder text consistently (e.g., YOUR_API_KEY)
• Test all code examples before publishing

Images and Media

• Include descriptive alt text for all images
• Keep images under 1MB when possible
• Use SVG format for diagrams and flowcharts
• Include captions for complex visuals
• Maintain consistent image dimensions within a document

Links and References

• Use descriptive link text (avoid "click here")
• Check all links before publishing
• Use relative links for internal documentation
• Include version numbers when linking to external documentation
• Provide context for why a link is relevant

Persona-Specific Guidelines

• Include persona activation phrase at the beginning
• Clearly indicate persona-specific sections
• Use consistent terminology for each persona
• Include cross-references to related personas
• Maintain consistent formatting across all persona documentation

Versioning

• Include last updated date in all documents
• Use semantic versioning for documentation (MAJOR.MINOR.PATCH)
• Maintain a changelog for significant updates
• Indicate deprecated features clearly
• Archive outdated documentation rather than deleting

Accessibility

• Use descriptive alt text for images
• Maintain proper heading hierarchy
• Use sufficient color contrast
• Avoid directional instructions ("click the button below")
• Provide text alternatives for non-text content

Review Process

• All documentation must undergo peer review
• Use the documentation checklist before submission
• Run automated checks for style compliance
• Test all procedures on a clean environment
• Validate all links and references

File Organization

• Use kebab-case for filenames
• Group related documents in logical folders
• Maintain consistent file extensions (.md)
• Include README.md files in each directory
• Follow the established directory structure

---

This style guide is maintained by the BMAD Documentation Team. Last updated: Current Date.