ldy26098
/
BMAD-METHOD
mirror of https://github.com/bmad-code-org/BMAD-METHOD.git
1
0
Fork 0
Code Packages Projects Releases Wiki Activity

docs: further optimize style guide as delta-only document 

- Add opener declaring adherence to Google Style Guide and Diataxis
- Remove generic Google style guide sections (Visual Hierarchy patterns,
  Tables constraints, Code Blocks, Lists, Assets)
- Remove Diataxis explainer content (Document Types table, "X documents
  do Y" explanatory sentences, Before/After example)
- Keep all project-specific structure templates and checklists
- Consolidate rules into single Project-Specific Rules table

Result: 367 lines (down from 597), pure delta document assuming
LLM training knowledge of baseline standards.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Alex Verkhovsky 2026-01-15 10:12:50 -08:00
parent ebf86ea1f4
commit f8be6d9a87
1 changed files with 54 additions and 283 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

337
docs/_STYLE_GUIDE.md
View File

@ -2,87 +2,23 @@
title: "Documentation Style Guide" title: "Documentation Style Guide"
--- ---
Guidelines for consistent documentation across the BMad Method project. 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.
## Universal Formatting Rules ## Project-Specific Rules
These rules apply to ALL document types. Violations fail review. | Rule | Specification |
|------|---------------|
| Rule | Rationale | | No horizontal rules (`---`) | Fragments reading flow |
|------|-----------| | No `####` headers | Use bold text or admonitions instead |
| No horizontal rules (`---`) | Fragment reading flow |
| No `####` headers | Visual noise; use bold text or admonitions |
| No "Related" or "Next:" sections | Sidebar handles navigation | | No "Related" or "Next:" sections | Sidebar handles navigation |
| No deeply nested lists | Hard to parse; break into sections | | No deeply nested lists | Break into sections instead |
| No code blocks for non-code | Confusing semantics | | No code blocks for non-code | Use admonitions for dialogue examples |
| No bold paragraphs for callouts | Use admonitions instead | | No bold paragraphs for callouts | Use admonitions instead |
| 1-2 admonitions per section max | Overuse creates noise | | 1-2 admonitions per section max | Tutorials allow 3-4 per major section |
| Table cells and long list items (5+) 1-2 sentences max | Walls of text; break into sections or link to details | | Table cells / list items | 1-2 sentences max |
| Header budget | 8-12 `##` per doc; 2-3 `###` per section |
## Visual Hierarchy ## Admonitions (Starlight Syntax)
### Patterns to Use
| Pattern | When to Use |
|---------|-------------|
| Whitespace + section headers | Content separation |
| Bold text within paragraphs | Inline emphasis |
| Admonitions | Callouts requiring attention |
| Tables | Structured comparisons (3+ items) |
| Flat lists | Scannable options |
### Header Budget
- `##` sections: 8-12 per document
- `###` subsections: 2-3 per `##` section max
- `####`: Never use
The structure templates in this guide show content flow, not 1:1 header mapping. Admonitions and inline elements appear within sections, not as separate headers.
### Header Naming
| Context | Style | Example |
|---------|-------|---------|
| Steps | Action verbs | "Install BMad", "Create Your Plan" |
| Reference | Nouns | "Common Questions", "Quick Reference" |
## Example: Before and After
**Before (violations):**
```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 (correct):**
```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.
:::
```
## Admonitions
Starlight admonition syntax:
```md ```md
:::tip[Title] :::tip[Title]
@ -111,33 +47,10 @@ Critical warnings only — data loss, security issues
| `:::caution[Important]` | Critical caveats | | `:::caution[Important]` | Critical caveats |
| `:::note[Example]` | Command/response examples | | `:::note[Example]` | Command/response examples |
### Rules ## Standard Table Formats
- Always include a title
- Keep content to 1-3 sentences (longer rarely needed)
- Never nest admonitions
## Tables
Use tables for:
- Phase descriptions
- Agent roles
- Command references
- Option comparisons
- Multi-attribute sequences
### Constraints
| Constraint | Value |
|------------|-------|
| Columns | 2-4 max |
| Cell content | Short |
| Text alignment | Left |
| Number alignment | Right |
### Standard Formats
**Phases:** **Phases:**
```md ```md
| Phase | Name | What Happens | | Phase | Name | What Happens |
|-------|------|--------------| |-------|------|--------------|
@ -146,6 +59,7 @@ Use tables for:
``` ```
**Commands:** **Commands:**
```md ```md
| Command | Agent | Purpose | | Command | Agent | Purpose |
|---------|-------|---------| |---------|-------|---------|
@ -153,53 +67,6 @@ Use tables for:
| `*prd` | PM | Create Product Requirements Document | | `*prd` | PM | Create Product Requirements Document |
``` ```
## Code Blocks
**Correct** — language-tagged command:
```md
```bash
npx bmad-method install
```
```
**Incorrect** — untagged dialogue:
````md
```
You: Do something
Agent: [Response here]
```
````
For dialogue examples, use admonitions:
```md
:::note[Example]
Run `workflow-status` and the agent will tell you the next recommended workflow.
:::
```
## Lists
**Flat lists (preferred):**
```md
- **Option A** — Description
- **Option B** — Description
- **Option C** — Description
```
**Numbered steps:**
```md
1. Load the **PM agent** in a new chat
2. Run the PRD workflow: `*prd`
3. Output: `PRD.md`
```
## Assets
| Element | Requirements |
|---------|--------------|
| **Links** | Descriptive text (not "click here"), site-relative paths |
| **Images** | Alt text required, italic caption below, SVG preferred, store in `./images/` |
## Folder Structure Blocks ## Folder Structure Blocks
Show in "What You've Accomplished" sections: Show in "What You've Accomplished" sections:
@ -215,23 +82,9 @@ your-project/
``` ```
```` ````
## Document Types
Select document type based on reader goal:
| Reader Goal | Document Type |
|-------------|---------------|
| Learn a complete workflow | Tutorial |
| Complete a specific task | How-To |
| Understand a concept | Explanation |
| Look up information | Reference |
| Find term definitions | Glossary |
## Tutorial Structure ## Tutorial Structure
Tutorials teach complete workflows to new users. Length: 200-400 lines. ```text
```
1. Title + Hook (1-2 sentences describing outcome) 1. Title + Hook (1-2 sentences describing outcome)
2. Version/Module Notice (info or warning admonition) (optional) 2. Version/Module Notice (info or warning admonition) (optional)
3. What You'll Learn (bullet list of outcomes) 3. What You'll Learn (bullet list of outcomes)
@ -264,9 +117,7 @@ Tutorials teach complete workflows to new users. Length: 200-400 lines.
## How-To Structure ## How-To Structure
How-to guides complete specific tasks for users who know basics. Length: 50-150 lines (shorter than tutorials, assumes prior knowledge). ```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) 3. When to Skip This (optional)
@ -278,21 +129,6 @@ How-to guides complete specific tasks for users who know basics. Length: 50-150
9. Next Steps (optional) 9. Next Steps (optional)
``` ```
### How-To Visual Elements
| Admonition | Use |
|------------|-----|
| `:::note[Prerequisites]` | Required dependencies, agents, prior steps |
| `:::tip[Pro Tip]` | Optional shortcuts |
| `:::caution[Common Mistake]` | Pitfalls to avoid |
| `:::note[Example]` | Brief inline usage |
Guidelines:
- 1-2 admonitions max
- Prerequisites as admonition
- Multiple tips: use flat list instead of admonition
- Very simple how-tos: skip admonitions entirely
### How-To Checklist ### How-To Checklist
- [ ] Hook starts with "Use the `X` workflow to..." - [ ] Hook starts with "Use the `X` workflow to..."
@ -303,33 +139,31 @@ Guidelines:
## Explanation Structure ## Explanation Structure
Explanation documents answer "What is X?" and "Why does X matter?"
### Types ### Types
| Type | Purpose | Example | | Type | Example |
|------|---------|---------| |------|---------|
| **Index/Landing** | Topic area overview with navigation | `core-concepts/index.md` | | **Index/Landing** | `core-concepts/index.md` |
| **Concept** | Define core concept | `what-are-agents.md` | | **Concept** | `what-are-agents.md` |
| **Feature** | Deep dive into capability | `quick-flow.md` | | **Feature** | `quick-flow.md` |
| **Philosophy** | Design decisions and rationale | `why-solutioning-matters.md` | | **Philosophy** | `why-solutioning-matters.md` |
| **FAQ** | Answer common questions | `brownfield-faq.md` | | **FAQ** | `brownfield-faq.md` |
### General Structure ### General Template
``` ```text
1. Title + Hook (1-2 sentences) 1. Title + Hook (1-2 sentences)
2. Overview/Definition (what it is, why it matters) 2. Overview/Definition (what it is, why it matters)
3. Key Concepts (### subsections) 3. Key Concepts (### subsections)
4. Comparison Table (optional) 4. Comparison Table (optional)
5. When to Use / When Not to Use (optional) 5. When to Use / When Not to Use (optional)
6. Diagram (optional - mermaid) 6. Diagram (optional - mermaid, 1 per doc max)
7. Next Steps (optional) 7. Next Steps (optional)
``` ```
### Index/Landing Pages ### Index/Landing Pages
``` ```text
1. Title + Hook (one sentence) 1. Title + Hook (one sentence)
2. Content Table (links with descriptions) 2. Content Table (links with descriptions)
3. Getting Started (numbered list) 3. Getting Started (numbered list)
@ -338,7 +172,7 @@ Explanation documents answer "What is X?" and "Why does X matter?"
### Concept Explainers ### Concept Explainers
``` ```text
1. Title + Hook (what it is) 1. Title + Hook (what it is)
2. Types/Categories (### subsections) (optional) 2. Types/Categories (### subsections) (optional)
3. Key Differences Table 3. Key Differences Table
@ -349,7 +183,7 @@ Explanation documents answer "What is X?" and "Why does X matter?"
### Feature Explainers ### Feature Explainers
``` ```text
1. Title + Hook (what it does) 1. Title + Hook (what it 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 3. When to Use / When Not to Use
@ -361,7 +195,7 @@ Explanation documents answer "What is X?" and "Why does X matter?"
### Philosophy/Rationale Documents ### Philosophy/Rationale Documents
``` ```text
1. Title + Hook (the principle) 1. Title + Hook (the principle)
2. The Problem 2. The Problem
3. The Solution 3. The Solution
@ -370,15 +204,6 @@ Explanation documents answer "What is X?" and "Why does X matter?"
6. When This Applies 6. When This Applies
``` ```
### Visual Elements
| Element | Use For |
|---------|---------|
| Comparison tables | Contrasting types, options, approaches |
| Mermaid diagrams | Process flows, decision trees (1 per doc max) |
| "Best for:" lists | Quick decision guidance |
| Code examples | Brief concept illustration |
### Explanation Checklist ### Explanation Checklist
- [ ] Hook states what document explains - [ ] Hook states what document explains
@ -386,26 +211,24 @@ Explanation documents answer "What is X?" and "Why does X matter?"
- [ ] Comparison tables for 3+ options - [ ] Comparison tables for 3+ options
- [ ] Diagrams have clear labels - [ ] Diagrams have clear labels
- [ ] Links to how-to guides for procedural questions - [ ] Links to how-to guides for procedural questions
- [ ] 2-3 admonitions max per document (1-2 per section) - [ ] 2-3 admonitions max per document
## Reference Structure ## Reference Structure
Reference documents answer "What are the options?" and "What does X do?" for users who know what they need.
### Types ### Types
| Type | Purpose | Example | | Type | Example |
|------|---------|---------| |------|---------|
| **Index/Landing** | Navigation to reference content | `workflows/index.md` | | **Index/Landing** | `workflows/index.md` |
| **Catalog** | Quick-reference item list | `agents/index.md` | | **Catalog** | `agents/index.md` |
| **Deep-Dive** | Detailed single-item reference | `document-project.md` | | **Deep-Dive** | `document-project.md` |
| **Configuration** | Settings and config docs | `core-tasks.md` | | **Configuration** | `core-tasks.md` |
| **Glossary** | Term definitions | `glossary/index.md` | | **Glossary** | `glossary/index.md` |
| **Comprehensive** | Extensive multi-item reference | `bmgd-workflows.md` | | **Comprehensive** | `bmgd-workflows.md` |
### Reference Index Pages ### Reference Index Pages
``` ```text
1. Title + Hook (one sentence) 1. Title + Hook (one sentence)
2. Content Sections (## for each category) 2. Content Sections (## for each category)
- Bullet list with links and descriptions - Bullet list with links and descriptions
@ -413,7 +236,7 @@ Reference documents answer "What are the options?" and "What does X do?" for use
### Catalog Reference ### Catalog Reference
``` ```text
1. Title + Hook 1. Title + Hook
2. Items (## for each item) 2. Items (## for each item)
- Brief description (one sentence) - Brief description (one sentence)
@ -421,13 +244,9 @@ Reference documents answer "What are the options?" and "What does X do?" for use
3. Universal/Shared (## section) (optional) 3. Universal/Shared (## section) (optional)
``` ```
Guidelines:
- Use `##` for items, not `###`
- Keep descriptions to 1 sentence
### Item Deep-Dive Reference ### Item Deep-Dive Reference
``` ```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
@ -440,7 +259,7 @@ Guidelines:
### Configuration Reference ### Configuration Reference
``` ```text
1. Title + Hook 1. Title + Hook
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)
@ -452,7 +271,7 @@ Guidelines:
### Comprehensive Reference Guide ### Comprehensive Reference Guide
``` ```text
1. Title + Hook 1. Title + Hook
2. Overview (## section) 2. Overview (## section)
- Diagram or table showing organization - Diagram or table showing organization
@ -462,11 +281,6 @@ Guidelines:
4. Next Steps (optional) 4. Next Steps (optional)
``` ```
Guidelines:
- Standardize fields across all items
- Tables for comparing multiple items
- 1 diagram max per document
### Reference Checklist ### Reference Checklist
- [ ] Hook states what document references - [ ] Hook states what document references
@ -478,11 +292,8 @@ Guidelines:
## Glossary Structure ## Glossary Structure
Glossaries provide compact, scannable term definitions.
### Layout Strategy
Starlight generates right-side "On this page" navigation from headers: Starlight generates right-side "On this page" navigation from headers:
- Categories as `##` headers — appear in right nav - Categories as `##` headers — appear in right nav
- Terms in tables — compact rows, not individual headers - Terms in tables — compact rows, not individual headers
- No inline TOC — right sidebar handles navigation - No inline TOC — right sidebar handles navigation
@ -505,43 +316,21 @@ Starlight generates right-side "On this page" navigation from headers:
| 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 term name in 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
Add italic context at definition start for limited-scope terms: 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
Reference category anchor (terms are not 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
- No catch-all sections
### Glossary Checklist ### Glossary Checklist
- [ ] Terms in tables, not individual headers - [ ] Terms in tables, not individual headers
- [ ] Terms alphabetized within categories - [ ] Terms alphabetized within categories
- [ ] No inline TOC
- [ ] Definitions 1-2 sentences - [ ] Definitions 1-2 sentences
- [ ] Context markers italicized - [ ] Context markers italicized
- [ ] Term names bolded in cells - [ ] Term names bolded in cells
@ -549,8 +338,6 @@ Reference category anchor (terms are not headers):
## FAQ Sections ## FAQ Sections
Structure:
```md ```md
## Questions ## Questions
@ -568,29 +355,13 @@ Yes. The SM agent has a `correct-course` workflow for handling scope changes.
**Have a question not answered here?** [Open an issue](...) or ask in [Discord](...). **Have a question not answered here?** [Open an issue](...) or ask in [Discord](...).
``` ```
Rules: ## Validation Commands
- TOC with jump links under `## Questions`
- `###` headers for questions (no `Q:` prefix)
- Direct answers (no `**A:**` prefix)
- End with CTA for unanswered questions
## Validation Steps Before submitting documentation changes:
Before submitting documentation changes, run from repo root: ```bash
npm run docs:fix-links # Preview link format fixes
1. **Fix link format** — Convert relative links to site-relative paths: npm run docs:fix-links -- --write # Apply fixes
```bash npm run docs:validate-links # Check links exist
npm run docs:fix-links # Preview npm run docs:build # Verify no build errors
npm run docs:fix-links -- --write # Apply ```
```
2. **Validate links** — Check links point to existing files:
```bash
npm run docs:validate-links # Preview
npm run docs:validate-links -- --write # Auto-fix
```
3. **Build the site** — Verify no build errors:
```bash
npm run docs:build
```