ros/BMAD-METHOD
1
0
Fork 0
mirror of https://github.com/bmad-code-org/BMAD-METHOD.git synced 2026-01-30 04:32:02 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'main' into docs/fix-docs-build

Browse Source
This commit is contained in:
Brian
2026-01-15 16:44:02 -06:00
committed by GitHub
parent bdd3529160 96f21be73e
commit b15a789df4
1 changed files with 200 additions and 599 deletions
Download Patch File Download Diff File Expand all files Collapse all files

799
docs/_STYLE_GUIDE.md
View File

@@ -2,416 +2,304 @@
title: "Documentation Style Guide" title: "Documentation Style Guide"
--- ---
Internal guidelines for maintaining consistent, high-quality documentation across the BMad Method project. This document is not included in the Starlight sidebar — it's for contributors and maintainers, not end users. This project adheres to the [Google Developer Documentation Style Guide](https://developers.google.com/style) and uses [Diataxis](https://diataxis.fr/) to structure content. Only project-specific conventions follow.
## Quick Principles ## Project-Specific Rules
1. **Clarity over brevity** — Be concise, but never at the cost of understanding | Rule | Specification |
2. **Consistent structure** — Follow established patterns so readers know what to expect |------|---------------|
3. **Strategic visuals** — Use admonitions, tables, and diagrams purposefully | No horizontal rules (`---`) | Fragments reading flow |
4. **Scannable content** — Headers, lists, and callouts help readers find what they need | No `####` headers | Use bold text or admonitions instead |
| No "Related" or "Next:" sections | Sidebar handles navigation |
| No deeply nested lists | Break into sections instead |
| No code blocks for non-code | Use admonitions for dialogue examples |
| No bold paragraphs for callouts | Use admonitions instead |
| 1-2 admonitions per section max | Tutorials allow 3-4 per major section |
| Table cells / list items | 1-2 sentences max |
| Header budget | 8-12 `##` per doc; 2-3 `###` per section |
## Validation Steps ## Admonitions (Starlight Syntax)
Before submitting documentation changes, run these checks from the repo root: ```md
:::tip[Title]
Shortcuts, best practices
:::
1. **Fix link format** — Convert relative links (`./`, `../`) to site-relative paths (`/path/`) :::note[Title]
```bash Context, definitions, examples, prerequisites
npm run docs:fix-links # Preview changes :::
npm run docs:fix-links -- --write # Apply changes
```
2. **Validate links** — Check all links point to existing files :::caution[Title]
```bash Caveats, potential issues
npm run docs:validate-links # Preview issues :::
npm run docs:validate-links -- --write # Auto-fix where possible
```
3. **Build the site** — Verify no build errors :::danger[Title]
```bash Critical warnings only — data loss, security issues
npm run docs:build :::
``` ```
### Standard Uses
| Admonition | Use For |
|------------|---------|
| `:::note[Prerequisites]` | Dependencies before starting |
| `:::tip[Quick Path]` | TL;DR summary at document top |
| `:::caution[Important]` | Critical caveats |
| `:::note[Example]` | Command/response examples |
## Standard Table Formats
**Phases:**
```md
| Phase | Name | What Happens |
|-------|------|--------------|
| 1 | Analysis | Brainstorm, research *(optional)* |
| 2 | Planning | Requirements — PRD or tech-spec *(required)* |
```
**Commands:**
```md
| Command | Agent | Purpose |
|---------|-------|---------|
| `*workflow-init` | Analyst | Initialize a new project |
| `*prd` | PM | Create Product Requirements Document |
```
## Folder Structure Blocks
Show in "What You've Accomplished" sections:
````md
```
your-project/
├── _bmad/ # BMad configuration
├── _bmad-output/
│ ├── PRD.md # Your requirements document
│ └── bmm-workflow-status.yaml # Progress tracking
└── ...
```
````
## Tutorial Structure ## Tutorial Structure
Every tutorial should follow this structure: ```text
1. Title + Hook (1-2 sentences describing outcome)
``` 2. Version/Module Notice (info or warning admonition) (optional)
1. Title + Hook (1-2 sentences describing the outcome)
2. Version/Module Notice (info or warning admonition as appropriate)
3. What You'll Learn (bullet list of outcomes) 3. What You'll Learn (bullet list of outcomes)
4. Prerequisites (info admonition) 4. Prerequisites (info admonition)
5. Quick Path (tip admonition - TL;DR summary) 5. Quick Path (tip admonition - TL;DR summary)
6. Understanding [Topic] (context before steps - tables for phases/agents) 6. Understanding [Topic] (context before steps - tables for phases/agents)
7. Installation (if applicable) 7. Installation (optional)
8. Step 1: [First Major Task] 8. Step 1: [First Major Task]
9. Step 2: [Second Major Task] 9. Step 2: [Second Major Task]
10. Step 3: [Third Major Task] 10. Step 3: [Third Major Task]
11. What You've Accomplished (summary + folder structure if applicable) 11. What You've Accomplished (summary + folder structure)
12. Quick Reference (commands table) 12. Quick Reference (commands table)
13. Common Questions (FAQ format) 13. Common Questions (FAQ format)
14. Getting Help (community links) 14. Getting Help (community links)
15. Key Takeaways (tip admonition - memorable points) 15. Key Takeaways (tip admonition)
``` ```
Not all sections are required for every tutorial, but this is the standard flow. ### Tutorial Checklist
- [ ] Hook describes outcome in 1-2 sentences
- [ ] "What You'll Learn" section present
- [ ] Prerequisites in admonition
- [ ] Quick Path TL;DR admonition at top
- [ ] Tables for phases, commands, agents
- [ ] "What You've Accomplished" section present
- [ ] Quick Reference table present
- [ ] Common Questions section present
- [ ] Getting Help section present
- [ ] Key Takeaways admonition at end
## How-To Structure ## How-To Structure
How-to guides are task-focused and shorter than tutorials. They answer "How do I do X?" for users who already understand the basics. ```text
```
1. Title + Hook (one sentence: "Use the `X` workflow to...") 1. Title + Hook (one sentence: "Use the `X` workflow to...")
2. When to Use This (bullet list of scenarios) 2. When to Use This (bullet list of scenarios)
3. When to Skip This (optional - for workflows that aren't always needed) 3. When to Skip This (optional)
4. Prerequisites (note admonition) 4. Prerequisites (note admonition)
5. Steps (numbered ### subsections) 5. Steps (numbered ### subsections)
6. What You Get (output/artifacts produced) 6. What You Get (output/artifacts produced)
7. Example (optional - concrete usage scenario) 7. Example (optional)
8. Tips (optional - best practices, common pitfalls) 8. Tips (optional)
9. Next Steps (optional - what to do after completion) 9. Next Steps (optional)
``` ```
Include sections only when they add value. A simple how-to might only need Hook, Prerequisites, Steps, and What You Get.
### How-To vs Tutorial
| Aspect | How-To | Tutorial |
|--------|--------|----------|
| **Length** | 50-150 lines | 200-400 lines |
| **Audience** | Users who know the basics | New users learning concepts |
| **Focus** | Complete a specific task | Understand a workflow end-to-end |
| **Sections** | 5-8 sections | 12-15 sections |
| **Examples** | Brief, inline | Detailed, step-by-step |
### How-To Visual Elements
Use admonitions strategically in how-to guides:
| Admonition | Use In How-To |
|------------|---------------|
| `:::note[Prerequisites]` | Required dependencies, agents, prior steps |
| `:::tip[Pro Tip]` | Optional shortcuts or best practices |
| `:::caution[Common Mistake]` | Pitfalls to avoid |
| `:::note[Example]` | Brief usage example inline with steps |
**Guidelines:**
- **1-2 admonitions max** per how-to (they're shorter than tutorials)
- **Prerequisites as admonition** makes scanning easier
- **Tips section** can be a flat list instead of admonition if there are multiple tips
- **Skip admonitions entirely** for very simple how-tos
### How-To Checklist ### How-To Checklist
Before submitting a how-to: - [ ] Hook starts with "Use the `X` workflow to..."
- [ ] "When to Use This" has 3-5 bullet points
- [ ] Hook is one clear sentence starting with "Use the `X` workflow to..." - [ ] Prerequisites listed
- [ ] When to Use This has 3-5 bullet points
- [ ] Prerequisites listed (admonition or flat list)
- [ ] Steps are numbered `###` subsections with action verbs - [ ] Steps are numbered `###` subsections with action verbs
- [ ] What You Get describes output artifacts - [ ] "What You Get" describes output artifacts
- [ ] No horizontal rules (`---`)
- [ ] No `####` headers
- [ ] No "Related" section (sidebar handles navigation)
- [ ] 1-2 admonitions maximum
## Explanation Structure ## Explanation Structure
Explanation documents help users understand concepts, features, and design decisions. They answer "What is X?" and "Why does X matter?" rather than "How do I do X?" ### Types
### Types of Explanation Documents | Type | Example |
|------|---------|
| **Index/Landing** | `core-concepts/index.md` |
| **Concept** | `what-are-agents.md` |
| **Feature** | `quick-flow.md` |
| **Philosophy** | `why-solutioning-matters.md` |
| **FAQ** | `brownfield-faq.md` |
| Type | Purpose | Example | ### General Template
|------|---------|---------|
| **Index/Landing** | Overview of a topic area with navigation | `core-concepts/index.md` |
| **Concept** | Define and explain a core concept | `what-are-agents.md` |
| **Feature** | Deep dive into a specific capability | `quick-flow.md` |
| **Philosophy** | Explain design decisions and rationale | `why-solutioning-matters.md` |
| **FAQ** | Answer common questions (see FAQ Sections below) | `brownfield-faq.md` |
### General Explanation Structure ```text
1. Title + Hook (1-2 sentences)
```
1. Title + Hook (1-2 sentences explaining the topic)
2. Overview/Definition (what it is, why it matters) 2. Overview/Definition (what it is, why it matters)
3. Key Concepts (### subsections for main ideas) 3. Key Concepts (### subsections)
4. Comparison Table (optional - when comparing options) 4. Comparison Table (optional)
5. When to Use / When Not to Use (optional - decision guidance) 5. When to Use / When Not to Use (optional)
6. Diagram (optional - mermaid for processes/flows) 6. Diagram (optional - mermaid, 1 per doc max)
7. Next Steps (optional - where to go from here) 7. Next Steps (optional)
``` ```
### Index/Landing Pages ### Index/Landing Pages
Index pages orient users within a topic area. ```text
1. Title + Hook (one sentence)
```
1. Title + Hook (one sentence overview)
2. Content Table (links with descriptions) 2. Content Table (links with descriptions)
3. Getting Started (numbered list for new users) 3. Getting Started (numbered list)
4. Choose Your Path (optional - decision tree for different goals) 4. Choose Your Path (optional - decision tree)
``` ```
**Example hook:** "Understanding the fundamental building blocks of the BMad Method."
### Concept Explainers ### Concept Explainers
Concept pages define and explain core ideas. ```text
1. Title + Hook (what it is)
2. Types/Categories (### subsections) (optional)
3. Key Differences Table
4. Components/Parts
5. Which Should You Use?
6. Creating/Customizing (pointer to how-to guides)
``` ```
1. Title + Hook (what it is in one sentence)
2. Types/Categories (if applicable, with ### subsections)
3. Key Differences Table (comparing types/options)
4. Components/Parts (breakdown of elements)
5. Which Should You Use? (decision guidance)
6. Creating/Customizing (brief pointer to how-to guides)
```
**Example hook:** "Agents are AI assistants that help you accomplish tasks. Each agent has a unique personality, specialized capabilities, and an interactive menu."
### Feature Explainers ### Feature Explainers
Feature pages provide deep dives into specific capabilities. ```text
1. Title + Hook (what it does)
```
1. Title + Hook (what the feature does)
2. Quick Facts (optional - "Perfect for:", "Time to:") 2. Quick Facts (optional - "Perfect for:", "Time to:")
3. When to Use / When Not to Use (with bullet lists) 3. When to Use / When Not to Use
4. How It Works (process overview, mermaid diagram if helpful) 4. How It Works (mermaid diagram optional)
5. Key Benefits (what makes it valuable) 5. Key Benefits
6. Comparison Table (vs alternatives if applicable) 6. Comparison Table (optional)
7. When to Graduate/Upgrade (optional - when to use something else) 7. When to Graduate/Upgrade (optional)
``` ```
**Example hook:** "Quick Spec Flow is a streamlined alternative to the full BMad Method for Quick Flow track projects."
### Philosophy/Rationale Documents ### Philosophy/Rationale Documents
Philosophy pages explain design decisions and reasoning. ```text
1. Title + Hook (the principle)
2. The Problem
3. The Solution
4. Key Principles (### subsections)
5. Benefits
6. When This Applies
``` ```
1. Title + Hook (the principle or decision)
2. The Problem (what issue this addresses)
3. The Solution (how this approach solves it)
4. Key Principles (### subsections for main ideas)
5. Benefits (what users gain)
6. When This Applies (scope of the principle)
```
**Example hook:** "Phase 3 (Solutioning) translates **what** to build (from Planning) into **how** to build it (technical design)."
### Explanation Visual Elements
Use these elements strategically in explanation documents:
| Element | Use For |
|---------|---------|
| **Comparison tables** | Contrasting types, options, or approaches |
| **Mermaid diagrams** | Process flows, phase sequences, decision trees |
| **"Best for:" lists** | Quick decision guidance |
| **Code examples** | Illustrating concepts (keep brief) |
**Guidelines:**
- **Use diagrams sparingly** — one mermaid diagram per document maximum
- **Tables over prose** — for any comparison of 3+ items
- **Avoid step-by-step instructions** — point to how-to guides instead
### Explanation Checklist ### Explanation Checklist
Before submitting an explanation document: - [ ] Hook states what document explains
- [ ] Content in scannable `##` sections
- [ ] Hook clearly states what the document explains - [ ] Comparison tables for 3+ options
- [ ] Content organized into scannable `##` sections - [ ] Diagrams have clear labels
- [ ] Comparison tables used for contrasting options - [ ] Links to how-to guides for procedural questions
- [ ] No horizontal rules (`---`) - [ ] 2-3 admonitions max per document
- [ ] No `####` headers
- [ ] No "Related" section (sidebar handles navigation)
- [ ] No "Next:" navigation links (sidebar handles navigation)
- [ ] Diagrams have clear labels and flow
- [ ] Links to how-to guides for "how do I do this?" questions
- [ ] 2-3 admonitions maximum
## Reference Structure ## Reference Structure
Reference documents provide quick lookup information for users who know what they're looking for. They answer "What are the options?" and "What does X do?" rather than explaining concepts or teaching skills. ### Types
### Types of Reference Documents | Type | Example |
|------|---------|
| Type | Purpose | Example | | **Index/Landing** | `workflows/index.md` |
|------|---------|---------| | **Catalog** | `agents/index.md` |
| **Index/Landing** | Navigation to reference content | `workflows/index.md` | | **Deep-Dive** | `document-project.md` |
| **Catalog** | Quick-reference list of items | `agents/index.md` | | **Configuration** | `core-tasks.md` |
| **Deep-Dive** | Detailed single-item reference | `document-project.md` | | **Glossary** | `glossary/index.md` |
| **Configuration** | Settings and config documentation | `core-tasks.md` | | **Comprehensive** | `bmgd-workflows.md` |
| **Glossary** | Term definitions | `glossary/index.md` |
| **Comprehensive** | Extensive multi-item reference | `bmgd-workflows.md` |
### Reference Index Pages ### Reference Index Pages
For navigation landing pages: ```text
```
1. Title + Hook (one sentence describing scope)
2. Content Sections (## for each category)
- Bullet list with links and brief descriptions
```
Keep these minimal — their job is navigation, not explanation.
### Catalog Reference (Item Lists)
For quick-reference lists of items:
```
1. Title + Hook (one sentence) 1. Title + Hook (one sentence)
2. Content Sections (## for each category)
- Bullet list with links and descriptions
```
### Catalog Reference
```text
1. Title + Hook
2. Items (## for each item) 2. Items (## for each item)
- Brief description (one sentence) - Brief description (one sentence)
- **Commands:** or **Key Info:** as flat list - **Commands:** or **Key Info:** as flat list
3. Universal/Shared (## section if applicable) 3. Universal/Shared (## section) (optional)
``` ```
**Guidelines:**
- Use `##` for items, not `###`
- No horizontal rules between items — whitespace is sufficient
- No "Related" section — sidebar handles navigation
- Keep descriptions to 1 sentence per item
### Item Deep-Dive Reference ### Item Deep-Dive Reference
For detailed single-item documentation: ```text
```
1. Title + Hook (one sentence purpose) 1. Title + Hook (one sentence purpose)
2. Quick Facts (optional note admonition) 2. Quick Facts (optional note admonition)
- Module, Command, Input, Output as list - Module, Command, Input, Output as list
3. Purpose/Overview (## section) 3. Purpose/Overview (## section)
4. How to Invoke (code block) 4. How to Invoke (code block)
5. Key Sections (## for each major aspect) 5. Key Sections (## for each aspect)
- Use ### for sub-options within sections - Use ### for sub-options
6. Notes/Caveats (tip or caution admonition) 6. Notes/Caveats (tip or caution admonition)
``` ```
**Guidelines:**
- Start with "quick facts" so readers immediately know scope
- Use admonitions for important caveats
- No "Related Documentation" section — sidebar handles this
### Configuration Reference ### Configuration Reference
For settings, tasks, and config documentation: ```text
1. Title + Hook
```
1. Title + Hook (one sentence explaining what these configure)
2. Table of Contents (jump links if 4+ items) 2. Table of Contents (jump links if 4+ items)
3. Items (## for each config/task) 3. Items (## for each config/task)
- **Bold summary** — one sentence describing what it does - **Bold summary** — one sentence
- **Use it when:** bullet list of scenarios - **Use it when:** bullet list
- **How it works:** numbered steps - **How it works:** numbered steps (3-5 max)
- **Output:** expected result (if applicable) - **Output:** expected result (optional)
``` ```
**Guidelines:**
- Table of contents only needed for 4+ items
- Keep "How it works" to 3-5 steps maximum
- No horizontal rules between items
### Glossary Reference
For term definitions:
```
1. Title + Hook (one sentence)
2. Navigation (jump links to categories)
3. Categories (## for each category)
- Terms (### for each term)
- Definition (1-3 sentences, no prefix)
- Related context or example (optional)
```
**Guidelines:**
- Group related terms into categories
- Keep definitions concise — link to explanation docs for depth
- Use `###` for terms (makes them linkable and scannable)
- No horizontal rules between terms
### Comprehensive Reference Guide ### Comprehensive Reference Guide
For extensive multi-item references: ```text
1. Title + Hook
```
1. Title + Hook (one sentence)
2. Overview (## section) 2. Overview (## section)
- Diagram or table showing organization - Diagram or table showing organization
3. Major Sections (## for each phase/category) 3. Major Sections (## for each phase/category)
- Items (### for each item) - Items (### for each item)
- Standardized fields: Command, Agent, Input, Output, Description - Standardized fields: Command, Agent, Input, Output, Description
- Optional: Steps, Features, Use when 4. Next Steps (optional)
4. Next Steps (optional — only if genuinely helpful)
``` ```
**Guidelines:**
- Standardize item fields across all items in the guide
- Use tables for comparing multiple items at once
- One diagram maximum per document
- No horizontal rules — use `##` sections for separation
### General Reference Guidelines
These apply to all reference documents:
| Do | Don't |
|----|-------|
| Use `##` for major sections, `###` for items within | Use `####` headers |
| Use whitespace for separation | Use horizontal rules (`---`) |
| Link to explanation docs for "why" | Explain concepts inline |
| Use tables for structured data | Use nested lists |
| Use admonitions for important notes | Use bold paragraphs for callouts |
| Keep descriptions to 1-2 sentences | Write paragraphs of explanation |
### Reference Admonitions
Use sparingly — 1-2 maximum per reference document:
| Admonition | Use In Reference |
|------------|------------------|
| `:::note[Prerequisites]` | Dependencies needed before using |
| `:::tip[Pro Tip]` | Shortcuts or advanced usage |
| `:::caution[Important]` | Critical caveats or warnings |
### Reference Checklist ### Reference Checklist
Before submitting a reference document: - [ ] Hook states what document references
- [ ] Structure matches reference type
- [ ] Hook clearly states what the document references
- [ ] Appropriate structure for reference type (catalog, deep-dive, etc.)
- [ ] No horizontal rules (`---`)
- [ ] No `####` headers
- [ ] No "Related" section (sidebar handles navigation)
- [ ] Items use consistent structure throughout - [ ] Items use consistent structure throughout
- [ ] Descriptions are 1-2 sentences maximum - [ ] Tables for structured/comparative data
- [ ] Tables used for structured/comparative data
- [ ] 1-2 admonitions maximum
- [ ] Links to explanation docs for conceptual depth - [ ] Links to explanation docs for conceptual depth
- [ ] 1-2 admonitions max
## Glossary Structure ## Glossary Structure
Glossaries provide quick-reference definitions for project terminology. Unlike other reference documents, glossaries prioritize compact scanability over narrative explanation. Starlight generates right-side "On this page" navigation from headers:
### Layout Strategy - Categories as `##` headers — appear in right nav
- Terms in tables — compact rows, not individual headers
Starlight auto-generates a right-side "On this page" navigation from headers. Use this to your advantage: - No inline TOC — right sidebar handles navigation
- **Categories as `##` headers** — Appear in right nav for quick jumping
- **Terms in tables** — Compact rows, not individual headers
- **No inline TOC** — Right sidebar handles navigation; inline TOC is redundant
- **Right nav shows categories only** — Cleaner than listing every term
This approach reduces content length by ~70% while improving navigation.
### Table Format ### Table Format
Each category uses a two-column table:
```md ```md
## Category Name ## Category Name
@@ -421,250 +309,35 @@ Each category uses a two-column table:
| **Workflow** | Multi-step guided process that orchestrates AI agent activities to produce deliverables. | | **Workflow** | Multi-step guided process that orchestrates AI agent activities to produce deliverables. |
``` ```
### Definition Guidelines ### Definition Rules
| Do | Don't | | Do | Don't |
|----|-------| |----|-------|
| Start with what it IS or DOES | Start with "This is..." or "A [term] is..." | | Start with what it IS or DOES | Start with "This is..." or "A [term] is..." |
| Keep to 1-2 sentences | Write multi-paragraph explanations | | Keep to 1-2 sentences | Write multi-paragraph explanations |
| Bold the term name in the cell | Use plain text for terms | | Bold term name in cell | Use plain text for terms |
| Link to docs for deep dives | Explain full concepts inline |
### Context Markers ### Context Markers
For terms with limited scope, add italic context at the start of the definition: Add italic context at definition start for limited-scope terms:
```md
| **Tech-Spec** | *Quick Flow only.* Comprehensive technical plan for small changes. |
| **PRD** | *BMad Method/Enterprise.* Product-level planning document with vision and goals. |
```
Standard markers:
- `*Quick Flow only.*` - `*Quick Flow only.*`
- `*BMad Method/Enterprise.*` - `*BMad Method/Enterprise.*`
- `*Phase N.*` - `*Phase N.*`
- `*BMGD.*` - `*BMGD.*`
- `*Brownfield.*` - `*Brownfield.*`
### Cross-References
Link related terms when helpful. Reference the category anchor since individual terms aren't headers:
```md
| **Tech-Spec** | *Quick Flow only.* Technical plan for small changes. See [PRD](#planning-documents). |
```
### Organization
- **Alphabetize terms** within each category table
- **Alphabetize categories** or order by logical progression (foundational → specific)
- **No catch-all sections** — Every term belongs in a specific category
### Glossary Checklist ### Glossary Checklist
Before submitting glossary changes:
- [ ] Terms in tables, not individual headers - [ ] Terms in tables, not individual headers
- [ ] Terms alphabetized within each category - [ ] Terms alphabetized within categories
- [ ] No inline TOC (right nav handles navigation) - [ ] Definitions 1-2 sentences
- [ ] No horizontal rules (`---`) - [ ] Context markers italicized
- [ ] Definitions are 1-2 sentences - [ ] Term names bolded in cells
- [ ] Context markers italicized at definition start
- [ ] Term names bolded in table cells
- [ ] No "A [term] is..." definitions - [ ] No "A [term] is..." definitions
## Visual Hierarchy
### Avoid
| Pattern | Problem |
|---------|---------|
| `---` horizontal rules | Fragment the reading flow |
| `####` deep headers | Create visual noise |
| **Important:** bold paragraphs | Blend into body text |
| Deeply nested lists | Hard to scan |
| Code blocks for non-code | Confusing semantics |
### Use Instead
| Pattern | When to Use |
|---------|-------------|
| White space + section headers | Natural content separation |
| Bold text within paragraphs | Inline emphasis |
| Admonitions | Callouts that need attention |
| Tables | Structured comparisons |
| Flat lists | Scannable options |
## Admonitions
Use Starlight admonitions strategically:
```md
:::tip[Title]
Shortcuts, best practices, "pro tips"
:::
:::note[Title]
Context, definitions, examples, prerequisites
:::
:::caution[Title]
Caveats, potential issues, things to watch out for
:::
:::danger[Title]
Critical warnings only — data loss, security issues
:::
```
### Standard Admonition Uses
| Admonition | Standard Use in Tutorials |
|------------|---------------------------|
| `:::note[Prerequisites]` | What users need before starting |
| `:::tip[Quick Path]` | TL;DR summary at top of tutorial |
| `:::caution[Fresh Chats]` | Context limitation reminders |
| `:::note[Example]` | Command/response examples |
| `:::tip[Check Your Status]` | How to verify progress |
| `:::tip[Remember These]` | Key takeaways at end |
### Admonition Guidelines
- **Always include a title** for tip, info, and warning
- **Keep content brief** — 1-3 sentences ideal
- **Don't overuse** — More than 3-4 per major section feels noisy
- **Don't nest** — Admonitions inside admonitions are hard to read
## Headers
### Budget
- **8-12 `##` sections** for full tutorials following standard structure
- **2-3 `###` subsections** per `##` section maximum
- **Avoid `####` entirely** — use bold text or admonitions instead
### Naming
- Use action verbs for steps: "Install BMad", "Create Your Plan"
- Use nouns for reference sections: "Common Questions", "Quick Reference"
- Keep headers short and scannable
## Code Blocks
### Do
```md
```bash
npx bmad-method install
```
```
### Don't
````md
```
You: Do something
Agent: [Response here]
```
````
For command/response examples, use an admonition instead:
```md
:::note[Example]
Run `workflow-status` and the agent will tell you the next recommended workflow.
:::
```
## Tables
Use tables for:
- Phases and what happens in each
- Agent roles and when to use them
- Command references
- Comparing options
- Step sequences with multiple attributes
Keep tables simple:
- 2-4 columns maximum
- Short cell content
- Left-align text, right-align numbers
### Standard Tables
**Phases Table:**
```md
| Phase | Name | What Happens |
|-------|------|--------------|
| 1 | Analysis | Brainstorm, research *(optional)* |
| 2 | Planning | Requirements — PRD or tech-spec *(required)* |
```
**Quick Reference Table:**
```md
| Command | Agent | Purpose |
|---------|-------|---------|
| `*workflow-init` | Analyst | Initialize a new project |
| `*prd` | PM | Create Product Requirements Document |
```
**Build Cycle Table:**
```md
| Step | Agent | Workflow | Purpose |
|------|-------|----------|---------|
| 1 | SM | `create-story` | Create story file from epic |
| 2 | DEV | `dev-story` | Implement the story |
```
## Lists
### Flat Lists (Preferred)
```md
- **Option A** — Description of option A
- **Option B** — Description of option B
- **Option C** — Description of option C
```
### Numbered Steps
```md
1. Load the **PM agent** in a new chat
2. Run the PRD workflow: `*prd`
3. Output: `PRD.md`
```
### Avoid Deep Nesting
```md
<!-- Don't do this -->
1. First step
- Sub-step A
- Detail 1
- Detail 2
- Sub-step B
2. Second step
```
Instead, break into separate sections or use an admonition for context.
## Links
- Use descriptive link text: `[Tutorial Style Guide](./tutorial-style.md)`
- Avoid "click here" or bare URLs
- Prefer relative paths within docs
## Images
- Always include alt text
- Add a caption in italics below: `*Description of the image.*`
- Use SVG for diagrams when possible
- Store in `./images/` relative to the document
## FAQ Sections ## FAQ Sections
Use a TOC with jump links, `###` headers for questions, and direct answers:
```md ```md
## Questions ## Questions
@@ -679,88 +352,16 @@ Only for BMad Method and Enterprise tracks. Quick Flow skips to implementation.
Yes. The SM agent has a `correct-course` workflow for handling scope changes. Yes. The SM agent has a `correct-course` workflow for handling scope changes.
**Have a question not answered here?** Please [open an issue](...) or ask in [Discord](...) so we can add it! **Have a question not answered here?** [Open an issue](...) or ask in [Discord](...).
``` ```
### FAQ Guidelines ## Validation Commands
- **TOC at top** — Jump links under `## Questions` for quick navigation Before submitting documentation changes:
- **`###` headers** — Questions are scannable and linkable (no `Q:` prefix)
- **Direct answers** — No `**A:**` prefix, just the answer
- **No "Related Documentation"** — Sidebar handles navigation; avoid repetitive links
- **End with CTA** — "Have a question not answered here?" with issue/Discord links
## Folder Structure Blocks
Show project structure in "What You've Accomplished":
````md
Your project now has:
```bash
npm run docs:fix-links # Preview link format fixes
npm run docs:fix-links -- --write # Apply fixes
npm run docs:validate-links # Check links exist
npm run docs:build # Verify no build errors
``` ```
your-project/
├── _bmad/ # BMad configuration
├── _bmad-output/
│ ├── PRD.md # Your requirements document
│ └── bmm-workflow-status.yaml # Progress tracking
└── ...
```
````
## Example: Before and After
### Before (Noisy)
```md
---
## Getting Started
### Step 1: Initialize
#### What happens during init?
**Important:** You need to describe your project.
1. Your project goals
- What you want to build
- Why you're building it
2. The complexity
- Small, medium, or large
---
```
### After (Clean)
```md
## Step 1: Initialize Your Project
Load the **Analyst agent** in your IDE, wait for the menu, then run `workflow-init`.
:::note[What Happens]
You'll describe your project goals and complexity. The workflow then recommends a planning track.
:::
```
## Checklist
Before submitting a tutorial:
- [ ] Follows the standard structure
- [ ] Has version/module notice if applicable
- [ ] Has "What You'll Learn" section
- [ ] Has Prerequisites admonition
- [ ] Has Quick Path TL;DR admonition
- [ ] No horizontal rules (`---`)
- [ ] No `####` headers
- [ ] Admonitions used for callouts (not bold paragraphs)
- [ ] Tables used for structured data (phases, commands, agents)
- [ ] Lists are flat (no deep nesting)
- [ ] Has "What You've Accomplished" section
- [ ] Has Quick Reference table
- [ ] Has Common Questions section
- [ ] Has Getting Help section
- [ ] Has Key Takeaways admonition
- [ ] All links use descriptive text
- [ ] Images have alt text and captions