# 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.*