ldy26098
/
BMAD-METHOD
mirror of https://github.com/bmad-code-org/BMAD-METHOD.git
1
0
Fork 0
Code Packages Projects Releases Wiki Activity
BMAD-METHOD/expansion-packs/bmad-technical-writing/docs/quick-reference.md

7.5 KiB
Raw Blame History

Quick Reference Card - Technical Writing Expansion Pack

One-page cheat sheet for most common workflows, agents, and commands.

Quick Start Command Sequence

For Writing Your First Chapter:

1. /bmad-tw:instructional-designer
   → *create-book-outline

2. /bmad-tw:instructional-designer
   → *create-chapter-outline

3. /bmad-tw:tutorial-architect
   → *outline-section (repeat for each section)

4. /bmad-tw:code-curator
   → *create-code-example

5. /bmad-tw:tutorial-architect
   → *create-tutorial (write section content)

6. /bmad-tw:technical-reviewer
   → *review-section

7. /bmad-tw:technical-editor
   → *assemble-chapter

8. /bmad-tw:book-publisher
   → *run-workflow packtpub-submission

Top 5 Workflows

# Workflow Use When Time
1 book-planning-workflow Starting new book, need approved outline 20-33 hrs
2 section-development-workflow Writing one section (2-5 pages) 5-10 hrs
3 chapter-assembly-workflow Merging sections into complete chapter 4-6 hrs
4 technical-review-workflow Validating technical accuracy 3-6 hrs
5 packtpub-submission-workflow Preparing for PacktPub submission 6-10 hrs

Top 5 Agents

# Agent Purpose Key Commands
1 Instructional Designer 🎓 Plan learning objectives, book structure *create-book-outline
*create-chapter-outline
*design-learning-path
2 Tutorial Architect 📝 Write tutorials, hands-on content *create-tutorial
*write-walkthrough
*design-exercises
3 Code Curator 💻 Create, test code examples *create-code-example
*test-code-examples
*setup-code-repository
4 Technical Reviewer 🔍 Verify technical accuracy, security *review-chapter
*audit-security
*verify-best-practices
5 Technical Editor ✍️ Polish writing, ensure consistency *assemble-chapter
*improve-clarity
*check-accessibility

Top 5 Checklists

# Checklist Use When Purpose
1 chapter-completeness-checklist After chapter assembly Ensure all required elements present
2 code-quality-checklist After code development Verify code standards met
3 technical-accuracy-checklist During technical review Validate correctness
4 packtpub-submission-checklist Before publisher submission Ensure PacktPub compliance
5 final-manuscript-checklist Before final submission Complete manuscript validation

Common Commands

Agent Control

  • *help - Show agent's available commands
  • *exit - Exit current agent

Document Creation

  • *create-doc <template> - Create document from template
  • *create-book-outline - Design book structure
  • *create-chapter-outline - Plan chapter sections
  • *create-tutorial - Write hands-on tutorial

Quality Assurance

  • *execute-checklist <checklist> - Run quality check
  • *review-chapter - Technical accuracy review
  • *test-code-examples - Verify code works

Publishing

  • *run-workflow <workflow> - Execute publishing workflow
  • *package-for-publisher - Prepare submission
  • *format-manuscript - Apply publisher standards

Decision Trees

Which Workflow Should I Use?

I want to...

  • Plan a new book → book-planning-workflow
  • Write one section → section-development-workflow
  • Complete a whole chapter → chapter-development-workflow
  • Review content → technical-review-workflow
  • Submit to PacktPub → packtpub-submission-workflow
  • Submit to O'Reilly → oreilly-submission-workflow
  • Submit to Manning → manning-meap-workflow
  • Self-publish → self-publishing-workflow
  • Update 2nd edition → book-edition-update-workflow
  • Add chapter to existing book → add-chapter-to-existing-book-workflow

Which Agent Should I Use?

I want to...

  • Design learning outcomes → Instructional Designer
  • Write tutorials → Tutorial Architect
  • Create code examples → Code Curator
  • Check technical accuracy → Technical Reviewer
  • Polish writing → Technical Editor
  • Prepare for publishing → Book Publisher
  • Document APIs → API Documenter
  • Create diagrams → Screenshot Specialist
  • Design exercises → Exercise Creator
  • Update existing book → Book Analyst

File Locations

Project Structure

your-book-project/
├── docs/
│   ├── planning/
│   │   ├── book-outline.md
│   │   └── chapter-outlines/
│   ├── sections/
│   │   └── chapter-01/
│   │       ├── section-1.1.md
│   │       └── section-1.2.md
│   ├── chapters/
│   │   └── chapter-01.md
│   └── reviews/
│       └── chapter-01-review.md
├── code-examples/
│   └── chapter-01/
└── submission/
    └── packtpub/

Typical Time Estimates

Activity Time
Book planning (outline) 20-33 hrs
Chapter outline 3-5 hrs
Section writing (2-5 pages) 5-10 hrs
Code example development 1-3 hrs
Technical review (chapter) 3-6 hrs
Chapter assembly 4-6 hrs
Publisher submission prep 6-10 hrs
Complete chapter (6 sections) 40-70 hrs

Section-Driven Development Summary

Break chapters into 2-5 page sections:

  1. Plan Sections - Instructional Designer creates section list
  2. Write Each Section - Tutorial Architect + Code Curator
  3. Review Sections - Technical Reviewer validates
  4. Assemble Chapter - Technical Editor merges

Benefits:

  • Manageable scope (small chunks)
  • Parallel development possible
  • Incremental progress visible
  • Quality easier to maintain

Quality Gates

Must Pass Before Moving Forward

After Book Outline:

  • ✅ All chapters have clear learning objectives
  • ✅ Prerequisites flow logically
  • ✅ No knowledge gaps between chapters

After Section Development:

  • ✅ Code examples tested and working
  • ✅ Technical review approved
  • ✅ 2-5 pages length appropriate
  • ✅ Learning objectives met

After Chapter Assembly:

  • ✅ Smooth transitions between sections
  • ✅ Introduction and summary present
  • ✅ Cross-references validated
  • ✅ Consistent style throughout

Before Publisher Submission:

  • ✅ All checklists passed
  • ✅ Code repository complete
  • ✅ Images/diagrams optimized
  • ✅ Publisher format requirements met

Next Steps

New to BMad Technical Writing?

  1. Read Getting Started Tutorial - 1-2 hours hands-on
  2. Review User Guide - Conceptual overview
  3. Start writing your first section!

Ready to Go Deep?

Need Help?

Print-Friendly Version

Save this page as PDF for quick reference while writing!

Quick Reference Card - Technical Writing Expansion Pack v1.1.0 Keep this handy while writing your technical book