110 lines
3.3 KiB
Markdown
110 lines
3.3 KiB
Markdown
# 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.*
|