BMAD-METHOD/docs/_contributing/tutorial-style.md

Tutorial Style Guide

Standards for writing tutorials and getting-started guides in BMAD documentation.

Structure

Every tutorial should follow this flow:

1. Title + Hook — What you'll accomplish (1-2 sentences)
2. Prerequisites — Use :::info[Prerequisites] if needed
3. What You'll Learn — Brief bullet list of outcomes
4. Main Steps — Numbered phases, minimal nesting
5. Summary + Next Steps — Wrap up, link forward

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 Docusaurus admonitions strategically:

:::tip[Title]
Shortcuts, best practices, "pro tips"
:::

:::info[Title]
Context, definitions, examples
:::

:::note
Supplementary information (can be collapsed)
:::

:::warning[Title]
Caveats, potential issues, things to watch out for
:::

:::danger[Title]
Critical warnings only — data loss, security issues
:::

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

• 5-7 ## sections maximum per tutorial
• 2-3 ### subsections per ## section maximum
• Avoid #### entirely — use bold text or admonitions instead

Naming

• Use action verbs for steps: "Install the CLI", "Configure Your Project"
• Use nouns for reference sections: "Common Questions", "Quick Reference"
• Keep headers short and scannable

Code Blocks

Do

```bash
npx bmad-method@alpha install

### Don't

````md

You: Do something Agent: [Response here]

For command/response examples, use an admonition instead:

:::info[Example]
Run `workflow-status` and the agent will tell you the next recommended workflow.
:::

Tables

Use tables for:

• Comparing options
• Mapping relationships (agent → document)
• Step sequences with multiple attributes

Keep tables simple:

• 2-4 columns maximum
• Short cell content
• Left-align text, right-align numbers

Lists

Flat Lists (Preferred)

- **Option A** — Description of option A
- **Option B** — Description of option B
- **Option C** — Description of option C

Numbered Steps

1. Load the **PM agent** in a new chat
2. Run the PRD workflow
3. Output: `PRD.md`

Avoid Deep Nesting

<!-- 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

Format as bold question followed by answer paragraph:

**Do I always need architecture?**
Only for BMad Method and Enterprise tracks. Quick Flow skips to implementation.

**Can I change my plan later?**
Yes. The SM agent has a `correct-course` workflow for handling scope changes.

Example: Before and After

Before (Noisy)

---

## 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)

## Step 1: Initialize Your Workflow

Load the **Analyst agent** in your IDE, wait for the menu, then run `workflow-init`.

:::info[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 (hook → learn → steps → summary)
• No horizontal rules (---)
• No #### headers
• Admonitions used for callouts (not bold paragraphs)
• Tables used for structured data
• Lists are flat (no deep nesting)
• 5-7 ## sections maximum
• All links use descriptive text
• Images have alt text and captions