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"
---
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 | Rationale |
|------|-----------|
| No horizontal rules (`---`) | Fragment reading flow |
| No `####` headers | Visual noise; use bold text or admonitions |
| Rule | Specification |
|------|---------------|
| No horizontal rules (`---`) | Fragments reading flow |
| No `####` headers | Use bold text or admonitions instead |
| No "Related" or "Next:" sections | Sidebar handles navigation |
| No deeply nested lists | Hard to parse; break into sections |
| No code blocks for non-code | Confusing semantics |
| 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 | Overuse creates noise |
| Table cells and long list items (5+) 1-2 sentences max | Walls of text; break into sections or link to details |
| 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 |
## Visual Hierarchy
### 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:
## Admonitions (Starlight Syntax)
```md
:::tip[Title]
@ -111,33 +47,10 @@ Critical warnings only — data loss, security issues
| `:::caution[Important]` | Critical caveats |
| `:::note[Example]` | Command/response examples |
### Rules
- 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
## Standard Table Formats
**Phases:**
```md
| Phase | Name | What Happens |
|-------|------|--------------|
@ -146,6 +59,7 @@ Use tables for:
```
**Commands:**
```md
| Command | Agent | Purpose |
|---------|-------|---------|
@ -153,53 +67,6 @@ Use tables for:
| `*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
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
Tutorials teach complete workflows to new users. Length: 200-400 lines.
```
```text
1. Title + Hook (1-2 sentences describing outcome)
2. Version/Module Notice (info or warning admonition) (optional)
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 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...")
2. When to Use This (bullet list of scenarios)
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)
```
### 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
- [ ] Hook starts with "Use the `X` workflow to..."
@ -303,33 +139,31 @@ Guidelines:
## Explanation Structure
Explanation documents answer "What is X?" and "Why does X matter?"
### Types
| Type | Purpose | Example |
|------|---------|---------|
| **Index/Landing** | Topic area overview with navigation | `core-concepts/index.md` |
| **Concept** | Define core concept | `what-are-agents.md` |
| **Feature** | Deep dive into capability | `quick-flow.md` |
| **Philosophy** | Design decisions and rationale | `why-solutioning-matters.md` |
| **FAQ** | Answer common questions | `brownfield-faq.md` |
| 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` |
### General Structure
### General Template
```
```text
1. Title + Hook (1-2 sentences)
2. Overview/Definition (what it is, why it matters)
3. Key Concepts (### subsections)
4. Comparison Table (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)
```
### Index/Landing Pages
```
```text
1. Title + Hook (one sentence)
2. Content Table (links with descriptions)
3. Getting Started (numbered list)
@ -338,7 +172,7 @@ Explanation documents answer "What is X?" and "Why does X matter?"
### Concept Explainers
```
```text
1. Title + Hook (what it is)
2. Types/Categories (### subsections) (optional)
3. Key Differences Table
@ -349,7 +183,7 @@ Explanation documents answer "What is X?" and "Why does X matter?"
### Feature Explainers
```
```text
1. Title + Hook (what it does)
2. Quick Facts (optional - "Perfect for:", "Time to:")
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
```
```text
1. Title + Hook (the principle)
2. The Problem
3. The Solution
@ -370,15 +204,6 @@ Explanation documents answer "What is X?" and "Why does X matter?"
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
- [ ] 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
- [ ] Diagrams have clear labels
- [ ] 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 documents answer "What are the options?" and "What does X do?" for users who know what they need.
### Types
| Type | Purpose | Example |
|------|---------|---------|
| **Index/Landing** | Navigation to reference content | `workflows/index.md` |
| **Catalog** | Quick-reference item list | `agents/index.md` |
| **Deep-Dive** | Detailed single-item reference | `document-project.md` |
| **Configuration** | Settings and config docs | `core-tasks.md` |
| **Glossary** | Term definitions | `glossary/index.md` |
| **Comprehensive** | Extensive multi-item reference | `bmgd-workflows.md` |
| Type | Example |
|------|---------|
| **Index/Landing** | `workflows/index.md` |
| **Catalog** | `agents/index.md` |
| **Deep-Dive** | `document-project.md` |
| **Configuration** | `core-tasks.md` |
| **Glossary** | `glossary/index.md` |
| **Comprehensive** | `bmgd-workflows.md` |
### Reference Index Pages
```
```text
1. Title + Hook (one sentence)
2. Content Sections (## for each category)
- 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
```
```text
1. Title + Hook
2. Items (## for each item)
- 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)
```
Guidelines:
- Use `##` for items, not `###`
- Keep descriptions to 1 sentence
### Item Deep-Dive Reference
```
```text
1. Title + Hook (one sentence purpose)
2. Quick Facts (optional note admonition)
- Module, Command, Input, Output as list
@ -440,7 +259,7 @@ Guidelines:
### Configuration Reference
```
```text
1. Title + Hook
2. Table of Contents (jump links if 4+ items)
3. Items (## for each config/task)
@ -452,7 +271,7 @@ Guidelines:
### Comprehensive Reference Guide
```
```text
1. Title + Hook
2. Overview (## section)
- Diagram or table showing organization
@ -462,11 +281,6 @@ Guidelines:
4. Next Steps (optional)
```
Guidelines:
- Standardize fields across all items
- Tables for comparing multiple items
- 1 diagram max per document
### Reference Checklist
- [ ] Hook states what document references
@ -478,11 +292,8 @@ Guidelines:
## Glossary Structure
Glossaries provide compact, scannable term definitions.
### Layout Strategy
Starlight generates right-side "On this page" navigation from headers:
- Categories as `##` headers — appear in right nav
- Terms in tables — compact rows, not individual headers
- 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..." |
| Keep to 1-2 sentences | Write multi-paragraph explanations |
| Bold term name in cell | Use plain text for terms |
| Link to docs for deep dives | Explain full concepts inline |
### Context Markers
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.*`
- `*BMad Method/Enterprise.*`
- `*Phase N.*`
- `*BMGD.*`
- `*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
- [ ] Terms in tables, not individual headers
- [ ] Terms alphabetized within categories
- [ ] No inline TOC
- [ ] Definitions 1-2 sentences
- [ ] Context markers italicized
- [ ] Term names bolded in cells
@ -549,8 +338,6 @@ Reference category anchor (terms are not headers):
## FAQ Sections
Structure:
```md
## 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](...).
```
Rules:
- TOC with jump links under `## Questions`
- `###` headers for questions (no `Q:` prefix)
- Direct answers (no `**A:**` prefix)
- End with CTA for unanswered questions
## Validation Commands
## Validation Steps
Before submitting documentation changes:
Before submitting documentation changes, run from repo root:
1. **Fix link format** — Convert relative links to site-relative paths:
```bash
npm run docs:fix-links # Preview
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
```
```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
```