mirror of
https://github.com/bmadcode/BMAD-METHOD.git
synced 2025-12-29 16:14:59 +00:00
docs: massive documentation overhaul + introduce Paige (Documentation Guide agent)
## 📚 Complete Documentation Restructure **BMM Documentation Hub Created:** - New centralized documentation system at `src/modules/bmm/docs/` - 18 comprehensive guides organized by topic (7000+ lines total) - Clear learning paths for greenfield, brownfield, and quick spec flows - Professional technical writing standards throughout **New Documentation:** - `README.md` - Complete documentation hub with navigation - `quick-start.md` - 15-minute getting started guide - `agents-guide.md` - Comprehensive 12-agent reference (45 min read) - `party-mode.md` - Multi-agent collaboration guide (20 min read) - `scale-adaptive-system.md` - Deep dive on Levels 0-4 (42 min read) - `brownfield-guide.md` - Existing codebase development (53 min read) - `quick-spec-flow.md` - Rapid Level 0-1 development (26 min read) - `workflows-analysis.md` - Phase 1 workflows (12 min read) - `workflows-planning.md` - Phase 2 workflows (19 min read) - `workflows-solutioning.md` - Phase 3 workflows (13 min read) - `workflows-implementation.md` - Phase 4 workflows (33 min read) - `workflows-testing.md` - Testing & QA workflows (29 min read) - `workflow-architecture-reference.md` - Architecture workflow deep-dive - `workflow-document-project-reference.md` - Document-project workflow reference - `enterprise-agentic-development.md` - Team collaboration patterns - `faq.md` - Comprehensive Q&A covering all topics - `glossary.md` - Complete terminology reference - `troubleshooting.md` - Common issues and solutions **Documentation Improvements:** - Removed all version/date footers (git handles versioning) - Agent customization docs now include full rebuild process - Cross-referenced links between all guides - Reading time estimates for all major docs - Consistent professional formatting and structure **Consolidated & Streamlined:** - Module README (`src/modules/bmm/README.md`) streamlined to lean signpost - Root README polished with better hierarchy and clear CTAs - Moved docs from root `docs/` to module-specific locations - Better separation of user docs vs. developer reference ## 🤖 New Agent: Paige (Documentation Guide) **Role:** Technical documentation specialist and information architect **Expertise:** - Professional technical writing standards - Documentation structure and organization - Information architecture and navigation - User-focused content design - Style guide enforcement **Status:** Work in progress - Paige will evolve as documentation needs grow **Integration:** - Listed in agents-guide.md, glossary.md, FAQ - Available for all phases (documentation is continuous) - Can be customized like all BMM agents ## 🔧 Additional Changes - Updated agent manifest with Paige - Updated workflow manifest with new documentation workflows - Fixed workflow-to-agent mappings across all guides - Improved root README with clearer Quick Start section - Better module structure explanations - Enhanced community links with Discord channel names **Total Impact:** - 18 new/restructured documentation files - 7000+ lines of professional technical documentation - Complete navigation system with cross-references - Clear learning paths for all user types - Foundation for knowledge base (coming in beta) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Brian Madison
238
bmad/bmm/workflows/techdoc/documentation-standards.md
Normal file
238
bmad/bmm/workflows/techdoc/documentation-standards.md
Normal file
@@ -0,0 +1,238 @@
|
||||
# Technical Documentation Standards for BMAD
|
||||
|
||||
**For Agent: Paige (Documentation Guide)**
|
||||
**Purpose: Concise reference for documentation creation and review**
|
||||
|
||||
---
|
||||
|
||||
## CRITICAL RULE: CommonMark Strict Compliance
|
||||
|
||||
ALL documentation MUST follow CommonMark specification exactly. No exceptions.
|
||||
|
||||
### CommonMark Essentials
|
||||
|
||||
**Headers:**
|
||||
|
||||
- Use ATX-style ONLY: `#` `##` `###` (NOT Setext underlines)
|
||||
- Single space after `#`: `# Title` (NOT `#Title`)
|
||||
- No trailing `#`: `# Title` (NOT `# Title #`)
|
||||
- Hierarchical order: Don't skip levels (h1→h2→h3, not h1→h3)
|
||||
|
||||
**Code Blocks:**
|
||||
|
||||
- Use fenced blocks with language identifier:
|
||||
````markdown
|
||||
```javascript
|
||||
const example = 'code';
|
||||
```
|
||||
````
|
||||
- NOT indented code blocks (ambiguous)
|
||||
|
||||
**Lists:**
|
||||
|
||||
- Consistent markers within list: all `-` or all `*` or all `+` (don't mix)
|
||||
- Proper indentation for nested items (2 or 4 spaces, stay consistent)
|
||||
- Blank line before/after list for clarity
|
||||
|
||||
**Links:**
|
||||
|
||||
- Inline: `[text](url)`
|
||||
- Reference: `[text][ref]` then `[ref]: url` at bottom
|
||||
- NO bare URLs without `<>` brackets
|
||||
|
||||
**Emphasis:**
|
||||
|
||||
- Italic: `*text*` or `_text_`
|
||||
- Bold: `**text**` or `__text__`
|
||||
- Consistent style within document
|
||||
|
||||
**Line Breaks:**
|
||||
|
||||
- Two spaces at end of line + newline, OR
|
||||
- Blank line between paragraphs
|
||||
- NO single line breaks (they're ignored)
|
||||
|
||||
---
|
||||
|
||||
## Mermaid Diagrams: Valid Syntax Required
|
||||
|
||||
**Critical Rules:**
|
||||
|
||||
1. Always specify diagram type first line
|
||||
2. Use valid Mermaid v10+ syntax
|
||||
3. Test syntax before outputting (mental validation)
|
||||
4. Keep focused: 5-10 nodes ideal, max 15
|
||||
|
||||
**Diagram Type Selection:**
|
||||
|
||||
- **flowchart** - Process flows, decision trees, workflows
|
||||
- **sequenceDiagram** - API interactions, message flows, time-based processes
|
||||
- **classDiagram** - Object models, class relationships, system structure
|
||||
- **erDiagram** - Database schemas, entity relationships
|
||||
- **stateDiagram-v2** - State machines, lifecycle stages
|
||||
- **gitGraph** - Branch strategies, version control flows
|
||||
|
||||
**Formatting:**
|
||||
|
||||
````markdown
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start[Clear Label] --> Decision{Question?}
|
||||
Decision -->|Yes| Action1[Do This]
|
||||
Decision -->|No| Action2[Do That]
|
||||
```
|
||||
````
|
||||
|
||||
---
|
||||
|
||||
## Style Guide Principles (Distilled)
|
||||
|
||||
Apply in this hierarchy:
|
||||
|
||||
1. **Project-specific guide** (if exists) - always ask first
|
||||
2. **BMAD conventions** (this document)
|
||||
3. **Google Developer Docs style** (defaults below)
|
||||
4. **CommonMark spec** (when in doubt)
|
||||
|
||||
### Core Writing Rules
|
||||
|
||||
**Task-Oriented Focus:**
|
||||
|
||||
- Write for user GOALS, not feature lists
|
||||
- Start with WHY, then HOW
|
||||
- Every doc answers: "What can I accomplish?"
|
||||
|
||||
**Clarity Principles:**
|
||||
|
||||
- Active voice: "Click the button" NOT "The button should be clicked"
|
||||
- Present tense: "The function returns" NOT "The function will return"
|
||||
- Direct language: "Use X for Y" NOT "X can be used for Y"
|
||||
- Second person: "You configure" NOT "Users configure" or "One configures"
|
||||
|
||||
**Structure:**
|
||||
|
||||
- One idea per sentence
|
||||
- One topic per paragraph
|
||||
- Headings describe content accurately
|
||||
- Examples follow explanations
|
||||
|
||||
**Accessibility:**
|
||||
|
||||
- Descriptive link text: "See the API reference" NOT "Click here"
|
||||
- Alt text for diagrams: Describe what it shows
|
||||
- Semantic heading hierarchy (don't skip levels)
|
||||
- Tables have headers
|
||||
|
||||
---
|
||||
|
||||
## OpenAPI/API Documentation
|
||||
|
||||
**Required Elements:**
|
||||
|
||||
- Endpoint path and method
|
||||
- Authentication requirements
|
||||
- Request parameters (path, query, body) with types
|
||||
- Request example (realistic, working)
|
||||
- Response schema with types
|
||||
- Response examples (success + common errors)
|
||||
- Error codes and meanings
|
||||
|
||||
**Quality Standards:**
|
||||
|
||||
- OpenAPI 3.0+ specification compliance
|
||||
- Complete schemas (no missing fields)
|
||||
- Examples that actually work
|
||||
- Clear error messages
|
||||
- Security schemes documented
|
||||
|
||||
---
|
||||
|
||||
## Documentation Types: Quick Reference
|
||||
|
||||
**README:**
|
||||
|
||||
- What (overview), Why (purpose), How (quick start)
|
||||
- Installation, Usage, Contributing, License
|
||||
- Under 500 lines (link to detailed docs)
|
||||
|
||||
**API Reference:**
|
||||
|
||||
- Complete endpoint coverage
|
||||
- Request/response examples
|
||||
- Authentication details
|
||||
- Error handling
|
||||
- Rate limits if applicable
|
||||
|
||||
**User Guide:**
|
||||
|
||||
- Task-based sections (How to...)
|
||||
- Step-by-step instructions
|
||||
- Screenshots/diagrams where helpful
|
||||
- Troubleshooting section
|
||||
|
||||
**Architecture Docs:**
|
||||
|
||||
- System overview diagram (Mermaid)
|
||||
- Component descriptions
|
||||
- Data flow
|
||||
- Technology decisions (ADRs)
|
||||
- Deployment architecture
|
||||
|
||||
**Developer Guide:**
|
||||
|
||||
- Setup/environment requirements
|
||||
- Code organization
|
||||
- Development workflow
|
||||
- Testing approach
|
||||
- Contribution guidelines
|
||||
|
||||
---
|
||||
|
||||
## Quality Checklist
|
||||
|
||||
Before finalizing ANY documentation:
|
||||
|
||||
- [ ] CommonMark compliant (no violations)
|
||||
- [ ] Headers in proper hierarchy
|
||||
- [ ] All code blocks have language tags
|
||||
- [ ] Links work and have descriptive text
|
||||
- [ ] Mermaid diagrams render correctly
|
||||
- [ ] Active voice, present tense
|
||||
- [ ] Task-oriented (answers "how do I...")
|
||||
- [ ] Examples are concrete and working
|
||||
- [ ] Accessibility standards met
|
||||
- [ ] Spelling/grammar checked
|
||||
- [ ] Reads clearly at target skill level
|
||||
|
||||
---
|
||||
|
||||
## BMAD-Specific Conventions
|
||||
|
||||
**File Organization:**
|
||||
|
||||
- `README.md` at root of each major component
|
||||
- `docs/` folder for extensive documentation
|
||||
- Workflow-specific docs in workflow folder
|
||||
- Cross-references use relative paths
|
||||
|
||||
**Frontmatter:**
|
||||
Use YAML frontmatter when appropriate:
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: Document Title
|
||||
description: Brief description
|
||||
author: Author name
|
||||
date: YYYY-MM-DD
|
||||
---
|
||||
```
|
||||
|
||||
**Metadata:**
|
||||
|
||||
- Always include last-updated date
|
||||
- Version info for versioned docs
|
||||
- Author attribution for accountability
|
||||
|
||||
---
|
||||
|
||||
**Remember: This is your foundation. Follow these rules consistently, and all documentation will be clear, accessible, and maintainable.**
|
||||
Reference in New Issue
Block a user