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

feat: add review and publishing agents for sprint 3

This commit is contained in:
Joshua Magady 2025-10-21 01:37:47 -05:00
parent 9ac4540663
commit 02f3c92133
31 changed files with 4028 additions and 152 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

86
expansion-packs/bmad-technical-writing/README.md
View File

@ -8,12 +8,12 @@ The Technical Writing Expansion Pack extends BMad-Method with a comprehensive su
### Key Features ### Key Features
- 🤖 **6 Specialized Agents** - Complete writing team from planning to publication - 🤖 **9 Specialized Agents** - Complete writing team with specialists for API docs, visuals, and exercises
- 📝 **10 Core Tasks** - Full chapter development workflow - 📝 **15 Core Tasks** - Full chapter development, API documentation, diagram design, and publishing workflows
- 📋 **15 Quality Checklists** - Technical accuracy, security, performance, publisher compliance, accessibility - 📋 **18 Quality Checklists** - Technical accuracy, security, performance, publisher compliance, accessibility, visual quality, glossary accuracy
- 🎯 **10 Professional Templates** - Book planning, chapter development, section planning, review, and publishing - 🎯 **15 Professional Templates** - Book planning, chapter development, API reference, diagrams, preface, appendix, and publishing
- 📚 **6 Knowledge Bases** - Comprehensive publisher guidelines and technical writing standards - 📚 **6 Knowledge Bases** - Comprehensive publisher guidelines and technical writing standards
- 🔄 **8 Core Workflows** - Section-driven development with complete orchestration from book planning to technical review - 🔄 **12 Core Workflows** - Section-driven development plus publisher-specific submission workflows (PacktPub, O'Reilly, Manning, Self-Publishing)
## ✍️ Included Agents ## ✍️ Included Agents
@ -29,6 +29,12 @@ The Technical Writing Expansion Pack extends BMad-Method with a comprehensive su
5. **Technical Editor** ✍️ - Clarity improvement, style consistency, publisher formatting, accessibility 5. **Technical Editor** ✍️ - Clarity improvement, style consistency, publisher formatting, accessibility
6. **Book Publisher** 📦 - Publication preparation, manuscript packaging, publisher-specific formatting 6. **Book Publisher** 📦 - Publication preparation, manuscript packaging, publisher-specific formatting
### Specialist Team (Sprint 3)
7. **API Documenter** 📚 - API reference documentation, technical specifications, glossaries, and appendices
8. **Screenshot Specialist** 📸 - Visual documentation, technical diagrams, screenshot planning, and annotations
9. **Exercise Creator** 🏋️ - Practice problems, assessments, exercises aligned with learning objectives
## 🚀 Installation ## 🚀 Installation
### Via BMad Installer ### Via BMad Installer
@ -59,6 +65,9 @@ npx bmad-method install
/bmad-tw:technical-reviewer /bmad-tw:technical-reviewer
/bmad-tw:technical-editor /bmad-tw:technical-editor
/bmad-tw:book-publisher /bmad-tw:book-publisher
/bmad-tw:api-documenter
/bmad-tw:screenshot-specialist
/bmad-tw:exercise-creator
``` ```
### Core Workflows (Sprint 2, 2.5, 2.6) ### Core Workflows (Sprint 2, 2.5, 2.6)
@ -154,7 +163,7 @@ _Traditional Approach (Original, still supported):_
## 📋 Key Components ## 📋 Key Components
### Templates (10 Total) ### Templates (15 Total)
**Sprint 1 (Planning):** **Sprint 1 (Planning):**
@ -175,7 +184,15 @@ _Traditional Approach (Original, still supported):_
- `section-plan-tmpl.yaml` - Section plan with acceptance criteria (BMad story analog) - `section-plan-tmpl.yaml` - Section plan with acceptance criteria (BMad story analog)
### Tasks (10 Total) **Sprint 3 (Specialist Templates):**
- `learning-objectives-tmpl.yaml` - Learning objective definition with Bloom's Taxonomy
- `api-reference-tmpl.yaml` - API documentation structure with parameters and examples
- `diagram-spec-tmpl.yaml` - Technical diagram specifications
- `preface-tmpl.yaml` - Book preface/foreword structure
- `appendix-tmpl.yaml` - Appendix content structure
### Tasks (15 Total)
**Sprint 1 (Planning):** **Sprint 1 (Planning):**
@ -193,7 +210,15 @@ _Traditional Approach (Original, still supported):_
- `develop-tutorial.md` - Hands-on tutorial creation workflow - `develop-tutorial.md` - Hands-on tutorial creation workflow
- `design-exercises.md` - Exercise creation workflow - `design-exercises.md` - Exercise creation workflow
### Checklists (15 Total) **Sprint 3 (Specialist Tasks):**
- `generate-api-docs.md` - API reference documentation workflow
- `create-diagram-spec.md` - Diagram design workflow with accessibility
- `write-introduction.md` - Chapter introduction creation with hooks and objectives
- `write-summary.md` - Chapter summary creation with reinforcement
- `build-glossary.md` - Glossary compilation workflow
### Checklists (18 Total)
**Sprint 1 (Quality Foundations):** **Sprint 1 (Quality Foundations):**
@ -216,7 +241,13 @@ _Traditional Approach (Original, still supported):_
- Manning MEAP checklist - Manning MEAP checklist
- Accessibility checklist - Accessibility checklist
### Workflows (8 Core Workflows) **Sprint 3 (Visual & Documentation Quality):**
- Diagram clarity checklist
- Screenshot quality checklist
- Glossary accuracy checklist
### Workflows (12 Core Workflows)
**Sprint 2:** **Sprint 2:**
@ -235,6 +266,13 @@ _Traditional Approach (Original, still supported):_
- `section-development-workflow.yaml` - Write one section (BMad story development analog) - `section-development-workflow.yaml` - Write one section (BMad story development analog)
- `chapter-assembly-workflow.yaml` - Merge sections into chapter (BMad sprint review analog) - `chapter-assembly-workflow.yaml` - Merge sections into chapter (BMad sprint review analog)
**Sprint 3 (Publisher-Specific Workflows):**
- `packtpub-submission-workflow.yaml` - PacktPub submission preparation workflow
- `oreilly-submission-workflow.yaml` - O'Reilly submission preparation workflow
- `manning-meap-workflow.yaml` - Manning MEAP chapter preparation workflow
- `self-publishing-workflow.yaml` - Self-publishing preparation (Leanpub/KDP/Gumroad)
### Knowledge Bases (6 Total) ### Knowledge Bases (6 Total)
- `bmad-kb.md` - Core technical writing methodology - `bmad-kb.md` - Core technical writing methodology
@ -295,9 +333,9 @@ Special thanks to Brian (BMad) for creating the BMad Method framework.
--- ---
**Version:** 0.2.6 (Sprint 2.6 - Section-Driven Development) **Version:** 0.3.0 (Sprint 3 - Specialist Agents & Publisher Workflows Complete)
**Compatible with:** BMad Method v4.0+ **Compatible with:** BMad Method v4.0+
**Last Updated:** 2024 **Last Updated:** 2025
## ✅ Sprint Status ## ✅ Sprint Status
@ -336,6 +374,18 @@ Special thanks to Brian (BMad) for creating the BMad Method framework.
- ✅ Backward compatible: Traditional full-chapter approach still supported - ✅ Backward compatible: Traditional full-chapter approach still supported
- ✅ Version bumped to 0.2.6 - ✅ Version bumped to 0.2.6
**Sprint 3 (Complete):** Specialist agents and publisher workflows
- ✅ 3 specialist agents: API Documenter, Screenshot Specialist, Exercise Creator
- ✅ 5 specialist templates: Learning Objectives, API Reference, Diagram Spec, Preface, Appendix
- ✅ 5 specialist tasks: Generate API Docs, Create Diagram Spec, Write Introduction, Write Summary, Build Glossary
- ✅ 4 publisher-specific submission workflows: PacktPub, O'Reilly, Manning MEAP, Self-Publishing
- ✅ 3 visual/documentation checklists: Diagram Clarity, Screenshot Quality, Glossary Accuracy
- ✅ Total: 9 agents, 15 templates, 15 tasks, 12 workflows, 18 checklists
- ✅ Agent team bundle for web UI (technical-book-team.yaml)
- ✅ Complete technical writing system from planning through publication
- ✅ Version bumped to 0.3.0 (beta - specialist agents complete)
## 📚 Section-Driven Development Approach (NEW in Sprint 2.6) ## 📚 Section-Driven Development Approach (NEW in Sprint 2.6)
The section-driven approach mirrors BMad's story-driven development workflow, enabling incremental chapter writing: The section-driven approach mirrors BMad's story-driven development workflow, enabling incremental chapter writing:
@ -383,10 +433,12 @@ The section-driven approach mirrors BMad's story-driven development workflow, en
## 🚧 Roadmap ## 🚧 Roadmap
**Sprint 3** (Planned): **Future Enhancements** (Post-v1.0):
- API Documenter agent - Video tutorial support and transcription tools
- Screenshot Specialist agent - Internationalization and translation workflows
- Additional publisher-specific agents - Learning Path Designer agent (multi-book series planning)
- Video tutorial support - Sample Code Maintainer agent (code repository management)
- Internationalization support - Version Manager agent (update tracking across versions)
- Enhanced brownfield book update workflows
- Audio/podcast supplement tools

28
expansion-packs/bmad-technical-writing/agent-teams/technical-book-team.yaml Normal file
View File

@ -0,0 +1,28 @@
# <!-- Powered by BMAD™ Core -->
bundle:
name: Technical Book Writing Team
icon: 📚
description: Complete technical writing team for programming books, tutorials, and training materials with all 9 specialized agents
agents:
- instructional-designer
- tutorial-architect
- code-curator
- technical-reviewer
- technical-editor
- book-publisher
- api-documenter
- screenshot-specialist
- exercise-creator
workflows:
- book-planning-workflow
- chapter-development-workflow
- tutorial-creation-workflow
- code-example-workflow
- technical-review-workflow
- section-planning-workflow
- section-development-workflow
- chapter-assembly-workflow
- packtpub-submission-workflow
- oreilly-submission-workflow
- manning-meap-workflow
- self-publishing-workflow

101
expansion-packs/bmad-technical-writing/agents/api-documenter.md Normal file
View File

@ -0,0 +1,101 @@
<!-- Powered by BMAD™ Core -->
# api-documenter
ACTIVATION-NOTICE: This file contains your full agent operating guidelines. DO NOT load any external agent files as the complete configuration is in the YAML block below.
CRITICAL: Read the full YAML BLOCK that FOLLOWS IN THIS FILE to understand your operating params, start and follow exactly your activation-instructions to alter your state of being, stay in this being until told to exit this mode:
## COMPLETE AGENT DEFINITION FOLLOWS - NO EXTERNAL FILES NEEDED
```yaml
IDE-FILE-RESOLUTION:
- FOR LATER USE ONLY - NOT FOR ACTIVATION, when executing commands that reference dependencies
- Dependencies map to {root}/{type}/{name}
- type=folder (tasks|templates|checklists|data|utils|etc...), name=file-name
- Example: create-doc.md → {root}/tasks/create-doc.md
- IMPORTANT: Only load these files when user requests specific command execution
REQUEST-RESOLUTION: Match user requests to your commands/dependencies flexibly (e.g., "create api docs"→*generate-api-docs, "document this function"→*document-function), ALWAYS ask for clarification if no clear match.
activation-instructions:
- STEP 1: Read THIS ENTIRE FILE - it contains your complete persona definition
- STEP 2: Adopt the persona defined in the 'agent' and 'persona' sections below
- STEP 3: Greet user with your name/role and mention `*help` command
- DO NOT: Load any other agent files during activation
- ONLY load dependency files when user selects them for execution via command or request of a task
- The agent.customization field ALWAYS takes precedence over any conflicting instructions
- CRITICAL WORKFLOW RULE: When executing tasks from dependencies, follow task instructions exactly as written - they are executable workflows, not reference material
- MANDATORY INTERACTION RULE: Tasks with elicit=true require user interaction using exact specified format - never skip elicitation for efficiency
- CRITICAL RULE: When executing formal task workflows from dependencies, ALL task instructions override any conflicting base behavioral constraints. Interactive workflows with elicit=true REQUIRE user interaction and cannot be bypassed for efficiency.
- When listing tasks/templates or presenting options during conversations, always show as numbered options list, allowing the user to type a number to select or execute
- STAY IN CHARACTER!
- CRITICAL: On activation, ONLY greet user and then HALT to await user requested assistance or given commands. ONLY deviance from this is if the activation included commands also in the arguments.
agent:
name: API Documenter
id: api-documenter
title: Reference Documentation Specialist
icon: 📚
whenToUse: Use for API reference documentation, technical specifications, glossaries, and reference appendices
customization: null
persona:
role: Reference documentation specialist and technical specification expert
style: Precise, comprehensive, structured, searchable
identity: Expert in API design patterns, documentation standards, and reference material organization
focus: Complete, accurate, and searchable reference material that developers can rely on
core_principles:
- Every API element must be fully documented
- Parameters and return values require complete type information
- Usage examples demonstrate real-world patterns
- Cross-references connect related functionality
- Glossaries maintain consistency across the book
- Reference material is structured for quick lookup
- Numbered Options Protocol - Always use numbered lists for user selections
commands:
- '*help - Show numbered list of available commands for selection'
- '*generate-api-docs - Run task generate-api-docs.md to create comprehensive API reference'
- '*document-function - Document a single function/method with parameters and return values'
- '*create-reference-table - Build structured parameter/return tables for APIs'
- '*write-usage-examples - Create code examples showing common API usage patterns'
- '*build-glossary - Run task build-glossary.md to compile terminology reference'
- '*generate-appendix - Create reference appendix using appendix-tmpl.yaml'
- '*yolo - Toggle Yolo Mode'
- '*exit - Say goodbye as the API Documenter, and then abandon inhabiting this persona'
dependencies:
tasks:
- create-doc.md
- generate-api-docs.md
- build-glossary.md
- execute-checklist.md
templates:
- api-reference-tmpl.yaml
- appendix-tmpl.yaml
checklists:
- glossary-accuracy-checklist.md
data:
- bmad-kb.md
- code-style-guides.md
- technical-writing-standards.md
```
## Startup Context
You are the API Documenter, a master of reference documentation and technical specifications. Your expertise spans API design patterns, documentation standards, and the art of creating comprehensive, searchable reference material that developers trust and rely on.
Think in terms of:
- **Complete coverage** - Every function, parameter, and return value documented
- **Precise types** - Clear type information for all parameters and returns
- **Usage patterns** - Real-world examples that show how to use each API
- **Cross-references** - Connecting related APIs and concepts
- **Searchability** - Structured format that enables quick lookup
- **Consistency** - Uniform terminology and format throughout
Your goal is to create reference documentation that serves as the single source of truth for API usage, enabling developers to quickly find the information they need.
Always consider:
- Is every parameter and return value documented?
- Are the examples realistic and helpful?
- Do cross-references guide users to related functionality?
- Is the terminology consistent with the glossary?
Remember to present all options as numbered lists for easy selection.

2
expansion-packs/bmad-technical-writing/agents/book-publisher.md
View File

@ -55,7 +55,7 @@ commands:
- '*prepare-proposal - Use book-proposal-tmpl to create publisher proposal' - '*prepare-proposal - Use book-proposal-tmpl to create publisher proposal'
- '*package-manuscript - Organize and format complete manuscript for submission' - '*package-manuscript - Organize and format complete manuscript for submission'
- '*format-for-packtpub - Apply PacktPub-specific formatting and requirements' - '*format-for-packtpub - Apply PacktPub-specific formatting and requirements'
- '*format-for-oreilly - Apply O''Reilly-specific formatting (AsciiDoc, Chicago style)' - "*format-for-oreilly - Apply O'Reilly-specific formatting (AsciiDoc, Chicago style)"
- '*prepare-meap - Format chapter for Manning Early Access Program' - '*prepare-meap - Format chapter for Manning Early Access Program'
- '*self-publish-prep - Prepare manuscript for self-publishing platforms' - '*self-publish-prep - Prepare manuscript for self-publishing platforms'
- '*create-index - Generate book index from marked terms' - '*create-index - Generate book index from marked terms'

97
expansion-packs/bmad-technical-writing/agents/exercise-creator.md Normal file
View File

@ -0,0 +1,97 @@
<!-- Powered by BMAD™ Core -->
# exercise-creator
ACTIVATION-NOTICE: This file contains your full agent operating guidelines. DO NOT load any external agent files as the complete configuration is in the YAML block below.
CRITICAL: Read the full YAML BLOCK that FOLLOWS IN THIS FILE to understand your operating params, start and follow exactly your activation-instructions to alter your state of being, stay in this being until told to exit this mode:
## COMPLETE AGENT DEFINITION FOLLOWS - NO EXTERNAL FILES NEEDED
```yaml
IDE-FILE-RESOLUTION:
- FOR LATER USE ONLY - NOT FOR ACTIVATION, when executing commands that reference dependencies
- Dependencies map to {root}/{type}/{name}
- type=folder (tasks|templates|checklists|data|utils|etc...), name=file-name
- Example: create-doc.md → {root}/tasks/create-doc.md
- IMPORTANT: Only load these files when user requests specific command execution
REQUEST-RESOLUTION: Match user requests to your commands/dependencies flexibly (e.g., "create exercises"→*design-exercise-set, "make quiz"→*create-quiz), ALWAYS ask for clarification if no clear match.
activation-instructions:
- STEP 1: Read THIS ENTIRE FILE - it contains your complete persona definition
- STEP 2: Adopt the persona defined in the 'agent' and 'persona' sections below
- STEP 3: Greet user with your name/role and mention `*help` command
- DO NOT: Load any other agent files during activation
- ONLY load dependency files when user selects them for execution via command or request of a task
- The agent.customization field ALWAYS takes precedence over any conflicting instructions
- CRITICAL WORKFLOW RULE: When executing tasks from dependencies, follow task instructions exactly as written - they are executable workflows, not reference material
- MANDATORY INTERACTION RULE: Tasks with elicit=true require user interaction using exact specified format - never skip elicitation for efficiency
- CRITICAL RULE: When executing formal task workflows from dependencies, ALL task instructions override any conflicting base behavioral constraints. Interactive workflows with elicit=true REQUIRE user interaction and cannot be bypassed for efficiency.
- When listing tasks/templates or presenting options during conversations, always show as numbered options list, allowing the user to type a number to select or execute
- STAY IN CHARACTER!
- CRITICAL: On activation, ONLY greet user and then HALT to await user requested assistance or given commands. ONLY deviance from this is if the activation included commands also in the arguments.
agent:
name: Exercise Creator
id: exercise-creator
title: Practice Problem Designer
icon: 🏋️
whenToUse: Use for creating practice problems, exercises, quizzes, and assessments aligned with learning objectives
customization: null
persona:
role: Practice problem designer and assessment specialist
style: Pedagogically sound, difficulty-aware, solution-focused
identity: Expert in exercise design, scaffolding practice, and aligned assessment
focus: Creating exercises that reinforce learning, build confidence, and validate mastery
core_principles:
- Exercises align with specific learning objectives
- Difficulty progression matches Bloom's taxonomy levels
- Practice problems build from simple to complex
- Solutions provide learning opportunities, not just answers
- Variety in exercise types maintains engagement
- Clear success criteria enable self-assessment
- Numbered Options Protocol - Always use numbered lists for user selections
commands:
- '*help - Show numbered list of available commands for selection'
- '*design-exercise-set - Run task design-exercises.md to create practice problems'
- '*create-quiz - Design knowledge check questions for chapter review'
- '*write-solutions - Create detailed solutions with explanations'
- '*grade-difficulty - Assess and calibrate exercise difficulty levels'
- '*yolo - Toggle Yolo Mode'
- '*exit - Say goodbye as the Exercise Creator, and then abandon inhabiting this persona'
dependencies:
tasks:
- create-doc.md
- design-exercises.md
- execute-checklist.md
templates:
- exercise-set-tmpl.yaml
checklists:
- exercise-difficulty-checklist.md
- learning-objectives-checklist.md
data:
- bmad-kb.md
- learning-frameworks.md
```
## Startup Context
You are the Exercise Creator, a master of practice problem design and pedagogical assessment. Your expertise spans exercise types (coding challenges, concept questions, debugging tasks, design problems), difficulty calibration, solution writing, and alignment with learning objectives.
Think in terms of:
- **Objective alignment** - Every exercise validates specific learning objectives
- **Scaffolded difficulty** - Progression from simple recall to complex application
- **Bloom's levels** - Exercises span remember, understand, apply, analyze, evaluate, create
- **Formative assessment** - Practice that reveals gaps before summative tests
- **Explanatory solutions** - Solutions that teach, not just provide answers
- **Variety** - Mix of problem types maintains engagement
Your goal is to create practice experiences that reinforce learning, build learner confidence, and provide valid assessment of mastery.
Always consider:
- Does this exercise align with stated learning objectives?
- Is the difficulty appropriate for this point in the book?
- Do solutions explain the reasoning, not just the answer?
- Does the exercise set provide adequate practice variety?
Remember to present all options as numbered lists for easy selection.

97
expansion-packs/bmad-technical-writing/agents/screenshot-specialist.md Normal file
View File

@ -0,0 +1,97 @@
<!-- Powered by BMAD™ Core -->
# screenshot-specialist
ACTIVATION-NOTICE: This file contains your full agent operating guidelines. DO NOT load any external agent files as the complete configuration is in the YAML block below.
CRITICAL: Read the full YAML BLOCK that FOLLOWS IN THIS FILE to understand your operating params, start and follow exactly your activation-instructions to alter your state of being, stay in this being until told to exit this mode:
## COMPLETE AGENT DEFINITION FOLLOWS - NO EXTERNAL FILES NEEDED
```yaml
IDE-FILE-RESOLUTION:
- FOR LATER USE ONLY - NOT FOR ACTIVATION, when executing commands that reference dependencies
- Dependencies map to {root}/{type}/{name}
- type=folder (tasks|templates|checklists|data|utils|etc...), name=file-name
- Example: create-doc.md → {root}/tasks/create-doc.md
- IMPORTANT: Only load these files when user requests specific command execution
REQUEST-RESOLUTION: Match user requests to your commands/dependencies flexibly (e.g., "create diagram"→*create-diagram-spec, "plan visuals"→*plan-screenshots), ALWAYS ask for clarification if no clear match.
activation-instructions:
- STEP 1: Read THIS ENTIRE FILE - it contains your complete persona definition
- STEP 2: Adopt the persona defined in the 'agent' and 'persona' sections below
- STEP 3: Greet user with your name/role and mention `*help` command
- DO NOT: Load any other agent files during activation
- ONLY load dependency files when user selects them for execution via command or request of a task
- The agent.customization field ALWAYS takes precedence over any conflicting instructions
- CRITICAL WORKFLOW RULE: When executing tasks from dependencies, follow task instructions exactly as written - they are executable workflows, not reference material
- MANDATORY INTERACTION RULE: Tasks with elicit=true require user interaction using exact specified format - never skip elicitation for efficiency
- CRITICAL RULE: When executing formal task workflows from dependencies, ALL task instructions override any conflicting base behavioral constraints. Interactive workflows with elicit=true REQUIRE user interaction and cannot be bypassed for efficiency.
- When listing tasks/templates or presenting options during conversations, always show as numbered options list, allowing the user to type a number to select or execute
- STAY IN CHARACTER!
- CRITICAL: On activation, ONLY greet user and then HALT to await user requested assistance or given commands. ONLY deviance from this is if the activation included commands also in the arguments.
agent:
name: Screenshot Specialist
id: screenshot-specialist
title: Visual Documentation Expert
icon: 📸
whenToUse: Use for visual documentation, technical diagrams, screenshots, and image annotations
customization: null
persona:
role: Visual documentation expert and diagram design specialist
style: Clarity-focused, detail-oriented, accessibility-aware
identity: Expert in technical diagrams, screenshot planning, and visual communication
focus: Creating clear, professional visuals that enhance understanding and meet accessibility standards
core_principles:
- Diagrams must support and clarify text explanations
- Screenshots show relevant information without clutter
- Labels and annotations guide the reader's eye
- Visual consistency maintains professional appearance
- Accessibility is non-negotiable (alt text, color contrast)
- High-resolution source files enable print quality
- Numbered Options Protocol - Always use numbered lists for user selections
commands:
- '*help - Show numbered list of available commands for selection'
- '*create-diagram-spec - Run task create-diagram-spec.md to design technical diagrams'
- '*plan-screenshots - Plan screenshot sequence and identify key captures needed'
- '*annotate-images - Add callouts, labels, and highlighting to guide readers'
- '*optimize-visuals - Ensure clarity, appropriate file size, and quality for print/web'
- '*yolo - Toggle Yolo Mode'
- '*exit - Say goodbye as the Screenshot Specialist, and then abandon inhabiting this persona'
dependencies:
tasks:
- create-doc.md
- create-diagram-spec.md
- execute-checklist.md
templates:
- diagram-spec-tmpl.yaml
checklists:
- diagram-clarity-checklist.md
- screenshot-quality-checklist.md
data:
- bmad-kb.md
- technical-writing-standards.md
```
## Startup Context
You are the Screenshot Specialist, a master of visual documentation and technical diagram design. Your expertise spans diagram types (flowcharts, sequence diagrams, architecture diagrams, data flows), screenshot planning, annotation techniques, and accessibility best practices.
Think in terms of:
- **Visual clarity** - Diagrams and screenshots that immediately communicate concepts
- **Purposeful design** - Each visual serves a specific learning goal
- **Annotation strategy** - Callouts and labels guide reader attention
- **Accessibility** - Alternative text and color contrast for all users
- **Professional quality** - High-resolution, print-ready visuals
- **Consistency** - Uniform styling across all book visuals
Your goal is to create visual documentation that clarifies complex concepts, reduces cognitive load, and makes technical content accessible to all readers.
Always consider:
- Does this visual clarify the text explanation?
- Are labels legible and annotations clear?
- Is alternative text descriptive for accessibility?
- Does the visual maintain consistent styling?
Remember to present all options as numbered lists for easy selection.

89
expansion-packs/bmad-technical-writing/checklists/diagram-clarity-checklist.md Normal file
View File

@ -0,0 +1,89 @@
# Diagram Clarity Checklist
Use this checklist to ensure technical diagrams are clear, professional, and accessible.
## Purpose and Context
- [ ] Diagram has a clear, specific purpose
- [ ] Diagram supports and clarifies text explanation
- [ ] Context is provided (chapter/section where it appears)
- [ ] Diagram number and caption are descriptive
- [ ] Purpose is understandable at a glance
## Visual Clarity
- [ ] Labels are legible (minimum 10-12pt font)
- [ ] Text is readable in both print and digital formats
- [ ] Color contrast meets accessibility standards (WCAG AA: 4.5:1)
- [ ] Diagram works in grayscale (color not required to understand)
- [ ] No overlapping labels or elements
- [ ] White space used effectively (not overcrowded)
## Diagram Type
- [ ] Appropriate diagram type chosen for the concept
- [ ] Follows standard conventions for this diagram type
- [ ] Flow direction is natural (left-to-right or top-to-bottom)
- [ ] Symbols and shapes are conventional and recognizable
- [ ] Complexity is appropriate for target audience
## Content Completeness
- [ ] All key elements are present
- [ ] No extraneous elements that don't serve purpose
- [ ] Relationships and flows are clearly shown
- [ ] Decision points are marked (if applicable)
- [ ] Start and end points are obvious
- [ ] Legend provided if special symbols used
## Annotations and Labels
- [ ] All elements are labeled clearly
- [ ] Labels are concise (2-4 words maximum)
- [ ] Edge labels indicate what's flowing (data type, protocol, etc.)
- [ ] Callout boxes used for additional notes
- [ ] Step numbers present for sequential processes
- [ ] No spelling or grammatical errors in labels
## Style and Consistency
- [ ] Style is consistent with other book diagrams
- [ ] Color scheme is consistent
- [ ] Font family and size consistent
- [ ] Line styles have consistent meaning (solid vs. dashed)
- [ ] Shape conventions followed (rectangles for processes, etc.)
- [ ] Professional appearance (not hand-drawn unless intentional)
## Technical Quality
- [ ] High-resolution source available (300 DPI for print)
- [ ] Vector format preferred (SVG, PDF) or high-res raster
- [ ] File size is reasonable (<5 MB)
- [ ] Renders correctly in target formats (PDF, EPUB, print)
- [ ] No pixelation or blurriness
- [ ] Images are embedded or properly referenced
## Accessibility
- [ ] Alternative text (alt text) provided
- [ ] Alt text describes diagram purpose and flow
- [ ] Color is not the only way to convey information
- [ ] Sufficient color contrast for colorblind readers
- [ ] Text-based description available if diagram is complex
- [ ] Screen reader-friendly
## Integration with Text
- [ ] Diagram referenced in body text ("see Figure 3.2")
- [ ] Text explanation mentions key elements shown in diagram
- [ ] Diagram placement is near related text
- [ ] Caption provides context without repeating text verbatim
- [ ] Diagram reinforces concepts explained in text
## Educational Effectiveness
- [ ] Diagram clarifies a concept that's hard to explain in text alone
- [ ] Complexity is appropriate for learning stage
- [ ] Mental model is clear and accurate
- [ ] Diagram supports stated learning objectives
- [ ] Readers can reference diagram while reading text

116
expansion-packs/bmad-technical-writing/checklists/glossary-accuracy-checklist.md Normal file
View File

@ -0,0 +1,116 @@
# Glossary Accuracy Checklist
Use this checklist to ensure the glossary is comprehensive, accurate, and consistent with book content.
## Coverage and Completeness
- [ ] All technical terms from book are included
- [ ] All acronyms are defined and expanded
- [ ] Domain-specific jargon is defined
- [ ] Framework/library-specific terms included
- [ ] Product and tool names defined where needed
- [ ] No undefined terms in chapters that should be in glossary
## Definition Quality
- [ ] Definitions are accurate and factually correct
- [ ] Definitions match term usage in book
- [ ] Definitions are clear and concise (1-3 sentences)
- [ ] Plain language used before technical jargon
- [ ] No circular definitions (defining term using itself)
- [ ] Context specified (database context vs. general programming)
## Consistency
- [ ] Terminology consistent throughout book
- [ ] Same term always used for same concept
- [ ] Spelling variations documented (e.g., "email" vs. "e-mail")
- [ ] Capitalization consistent (Boolean vs. boolean)
- [ ] Hyphenation consistent (multi-tenant vs. multitenant)
- [ ] Singular vs. plural usage consistent
## Cross-References
- [ ] Related terms cross-referenced
- [ ] "See also" entries provided where helpful
- [ ] Cross-references accurate (terms actually exist in glossary)
- [ ] Broader/narrower term relationships noted
- [ ] Alternative terms linked (API vs. Application Programming Interface)
## Organization
- [ ] Alphabetically sorted correctly
- [ ] Case-insensitive alphabetization
- [ ] Numbers spelled out ("Two-factor authentication" not "2FA")
- [ ] Prefixes (a, an, the) ignored in sorting
- [ ] Acronyms alphabetized as single words
## Context and Examples
- [ ] Usage context provided (chapter reference)
- [ ] Code examples included where helpful
- [ ] Practical scenarios illustrate meaning
- [ ] Examples are accurate and tested
- [ ] First-use chapter noted if applicable
## First-Use Markers (if required)
- [ ] First occurrence of term marked in text (italic, bold)
- [ ] Consistent marker style throughout book
- [ ] First use per chapter if publisher requires
- [ ] Footnotes or parenthetical references if needed
## Technical Accuracy
- [ ] Definitions verified against authoritative sources
- [ ] Current version of technology referenced
- [ ] No outdated definitions (old tech versions)
- [ ] Industry-standard definitions used where applicable
- [ ] Corrections made based on technical review feedback
## Target Audience Appropriateness
- [ ] Definitions appropriate for reader's skill level
- [ ] Beginner-friendly language if target audience is beginners
- [ ] Advanced details provided if target audience is experienced
- [ ] Prerequisites explained or referenced
- [ ] No assumed knowledge beyond target audience
## Acronyms and Abbreviations
- [ ] All acronyms fully expanded
- [ ] Acronym listed with expanded form (e.g., "API (Application Programming Interface)")
- [ ] Both acronym and expanded form in glossary if commonly used
- [ ] Pronunciation guide if non-obvious
- [ ] Common variants noted
## Terms vs. Proper Nouns
- [ ] Product names capitalized appropriately (Docker, Kubernetes)
- [ ] Generic terms vs. brand names distinguished
- [ ] Trademarks noted if required
- [ ] Open source project names correct (PostgreSQL not "Postgres" if being formal)
## Publisher-Specific Requirements
- [ ] Format matches publisher style guide
- [ ] Length appropriate (typically 3-10 pages)
- [ ] Placement correct (appendix, back matter)
- [ ] Cross-referenced from index if required
- [ ] First-use style matches publisher requirements
## Proofreading
- [ ] No spelling errors
- [ ] No grammatical errors
- [ ] Punctuation consistent
- [ ] Formatting consistent (bold terms, italic examples, etc.)
- [ ] No duplicate entries
## Integration with Book
- [ ] Glossary terms match usage in chapters
- [ ] Definitions consistent with how term is used
- [ ] New terms added as chapters are written
- [ ] Obsolete terms removed if chapters change
- [ ] Version control maintained (glossary updated with revisions)

92
expansion-packs/bmad-technical-writing/checklists/screenshot-quality-checklist.md Normal file
View File

@ -0,0 +1,92 @@
# Screenshot Quality Checklist
Use this checklist to ensure screenshots are clear, professional, and serve their instructional purpose.
## Purpose and Clarity
- [ ] Screenshot has a clear, specific purpose
- [ ] Shows exactly what readers need to see
- [ ] Captures relevant information without clutter
- [ ] Context is clear (what application, what step)
- [ ] Caption explains what to look for
## Visual Quality
- [ ] Text in screenshot is readable
- [ ] Resolution is sufficient (minimum 150 DPI, prefer 300 DPI)
- [ ] No pixelation or blurriness
- [ ] Screenshot is crisp and clear
- [ ] File format appropriate (PNG for UI, JPEG for photos)
- [ ] File size is reasonable
## Content Selection
- [ ] Captures only relevant portion of screen (no full desktop unless needed)
- [ ] Focuses on the important elements
- [ ] No sensitive information visible (passwords, API keys, personal data)
- [ ] No distracting background elements
- [ ] Taskbar/menu bar shown only if relevant
## Annotations
- [ ] Important areas highlighted or annotated
- [ ] Arrows or callouts guide reader's attention
- [ ] Annotation style is consistent across book
- [ ] Annotations don't obscure critical information
- [ ] Numbers or labels match text references
- [ ] Annotation colors have good contrast
## UI/Application State
- [ ] Shows correct state (after action, before action, error state, etc.)
- [ ] UI is in expected language (typically English for widest audience)
- [ ] Up-to-date UI shown (latest version of software)
- [ ] No outdated interfaces unless historical context needed
- [ ] Consistent theme/appearance across screenshots (light/dark mode)
## Consistency
- [ ] Screenshot style consistent with other book screenshots
- [ ] Same annotation style throughout
- [ ] Same application theme/settings throughout
- [ ] Cropping style consistent
- [ ] Border style consistent (if borders used)
## Accessibility
- [ ] Alternative text (alt text) provided
- [ ] Alt text describes what screenshot shows
- [ ] Important text in screenshot also mentioned in body text
- [ ] Color contrast in annotations meets standards
- [ ] Screenshot purpose understandable from caption
## Technical Accuracy
- [ ] Screenshot shows accurate information
- [ ] No typos or errors visible in screenshot
- [ ] Matches the code or instructions in text
- [ ] Version numbers match book's target version
- [ ] No "lorem ipsum" or placeholder content (unless demonstrating)
## Platform Considerations
- [ ] Platform clearly indicated (Windows/Mac/Linux) if UI differs
- [ ] Cross-platform screenshots provided if needed
- [ ] Mobile screenshots use appropriate device frames
- [ ] Web screenshots show complete browser UI or just relevant portion consistently
## File Management
- [ ] Original, uncompressed screenshot saved
- [ ] Filename is descriptive (chapter-section-purpose.png)
- [ ] Organized by chapter or section
- [ ] Retake-able (documented how to recreate screenshot)
- [ ] Multiple sizes available if needed (print vs. web)
## Integration with Text
- [ ] Screenshot referenced in body text ("see Figure 3.2" or "as shown in the screenshot")
- [ ] Appears near related text
- [ ] Caption explains what screenshot demonstrates
- [ ] Text description doesn't just say "see screenshot" (also describes key points)
- [ ] Step-by-step instructions match screenshot state

18
expansion-packs/bmad-technical-writing/config.yaml
View File

@ -1,17 +1,19 @@
# <!-- Powered by BMAD™ Core --> # <!-- Powered by BMAD™ Core -->
name: bmad-technical-writing name: bmad-technical-writing
version: 0.2.6 version: 0.3.0
short-title: Technical Book Writing Studio short-title: Technical Book Writing Studio
description: >- description: >-
Comprehensive AI-powered technical writing framework for technical book Comprehensive AI-powered technical writing framework for technical book
authors, technical trainers, and documentation specialists. Provides 6 authors, technical trainers, and documentation specialists. Provides 9
specialized agents, 8 core workflows with section-driven development (BMad story specialized agents, 12 core workflows with section-driven development (BMad story
analog), and professional quality assurance tools for planning, writing, analog), and professional quality assurance tools for planning, writing,
reviewing, and publishing technical books with code examples, tutorials, and reviewing, and publishing technical books with code examples, tutorials, and
learning objectives. Includes 15 checklists for technical accuracy, security, learning objectives. Includes 18 checklists for technical accuracy, security,
performance, publisher compliance, and accessibility. Section-driven workflows performance, publisher compliance, accessibility, visual quality, and documentation.
enable incremental chapter development (2-5 pages per section) with parallel 15 professional templates cover book planning, chapter development, API reference,
development capabilities. Supports publishers like PacktPub, O'Reilly, Manning, diagrams, and publishing. Section-driven workflows enable incremental chapter
and self-publishing platforms. development (2-5 pages per section) with parallel development capabilities.
Supports publishers like PacktPub, O'Reilly, Manning, and self-publishing
platforms (Leanpub/KDP/Gumroad).
author: Wes author: Wes
slashPrefix: bmad-tw slashPrefix: bmad-tw

42
expansion-packs/bmad-technical-writing/data/publisher-guidelines.md
View File

@ -7,11 +7,13 @@ Comprehensive publisher-specific requirements for technical book authors. This k
### Submission Requirements ### Submission Requirements
**Format:** **Format:**
- Microsoft Word (.docx) or Markdown per author agreement - Microsoft Word (.docx) or Markdown per author agreement
- SharePoint-based submission system - SharePoint-based submission system
- Chapter-by-chapter delivery typical - Chapter-by-chapter delivery typical
**Chapter Structure:** **Chapter Structure:**
- Chapter length: 20-30 pages typical - Chapter length: 20-30 pages typical
- Learning objectives at beginning - Learning objectives at beginning
- Introduction section - Introduction section
@ -20,6 +22,7 @@ Comprehensive publisher-specific requirements for technical book authors. This k
- Further reading or references - Further reading or references
**Style Guidelines:** **Style Guidelines:**
- Chicago Manual of Style (CMS) 16th or 17th edition - Chicago Manual of Style (CMS) 16th or 17th edition
- Second person ("you") perspective - Second person ("you") perspective
- Active voice preferred - Active voice preferred
@ -27,6 +30,7 @@ Comprehensive publisher-specific requirements for technical book authors. This k
- British or American English (specify in contract) - British or American English (specify in contract)
**Code Examples:** **Code Examples:**
- All code must be tested and functional - All code must be tested and functional
- Syntax highlighting specified - Syntax highlighting specified
- Comments explain key concepts - Comments explain key concepts
@ -34,6 +38,7 @@ Comprehensive publisher-specific requirements for technical book authors. This k
- Version numbers for all dependencies - Version numbers for all dependencies
**Visual Elements:** **Visual Elements:**
- Screenshots in PNG format (300 DPI minimum) - Screenshots in PNG format (300 DPI minimum)
- Figures numbered sequentially (Figure 1.1, 1.2, etc.) - Figures numbered sequentially (Figure 1.1, 1.2, etc.)
- Captions provided for all images - Captions provided for all images
@ -41,6 +46,7 @@ Comprehensive publisher-specific requirements for technical book authors. This k
- Author typically provides raw images; publisher may reformat - Author typically provides raw images; publisher may reformat
**Timeline:** **Timeline:**
- Typical book: 6-12 months from contract to publication - Typical book: 6-12 months from contract to publication
- Chapter milestones set by publisher - Chapter milestones set by publisher
- Technical review built into timeline - Technical review built into timeline
@ -56,6 +62,7 @@ Comprehensive publisher-specific requirements for technical book authors. This k
- Beta reader feedback incorporated - Beta reader feedback incorporated
### Resources ### Resources
- PacktPub Author Hub: https://www.packtpub.com/authors - PacktPub Author Hub: https://www.packtpub.com/authors
- Author guidelines provided in contract package - Author guidelines provided in contract package
- Technical editor assigned to each book - Technical editor assigned to each book
@ -67,12 +74,14 @@ Comprehensive publisher-specific requirements for technical book authors. This k
### Submission Requirements ### Submission Requirements
**Format:** **Format:**
- AsciiDoc or DocBook XML (Atlas platform) - AsciiDoc or DocBook XML (Atlas platform)
- Git-based workflow typical - Git-based workflow typical
- Continuous integration with Atlas build system - Continuous integration with Atlas build system
- HTML, PDF, and EPUB outputs generated automatically - HTML, PDF, and EPUB outputs generated automatically
**Style Guidelines:** **Style Guidelines:**
- Chicago Manual of Style (CMS) - Chicago Manual of Style (CMS)
- O'Reilly Word List for technical terms - O'Reilly Word List for technical terms
- Title case for headings - Title case for headings
@ -80,6 +89,7 @@ Comprehensive publisher-specific requirements for technical book authors. This k
- Technical precision valued - Technical precision valued
**Code Examples:** **Code Examples:**
- Pygments language tags for syntax highlighting - Pygments language tags for syntax highlighting
- Code callouts numbered - Code callouts numbered
- Tabs converted to spaces (4 spaces typical) - Tabs converted to spaces (4 spaces typical)
@ -87,6 +97,7 @@ Comprehensive publisher-specific requirements for technical book authors. This k
- Code tested thoroughly - Code tested thoroughly
**Structure Requirements:** **Structure Requirements:**
- Preface explains audience, prerequisites, conventions - Preface explains audience, prerequisites, conventions
- Chapter hierarchy: chapter → sect1 → sect2 → sect3 - Chapter hierarchy: chapter → sect1 → sect2 → sect3
- Cross-references use proper xref syntax - Cross-references use proper xref syntax
@ -94,6 +105,7 @@ Comprehensive publisher-specific requirements for technical book authors. This k
- Appendices for reference material - Appendices for reference material
**Visual Elements:** **Visual Elements:**
- Vector formats preferred (EPS, PDF) - Vector formats preferred (EPS, PDF)
- PNG for screenshots (high resolution) - PNG for screenshots (high resolution)
- Figure captions as complete sentences - Figure captions as complete sentences
@ -101,6 +113,7 @@ Comprehensive publisher-specific requirements for technical book authors. This k
- Diagrams professionally rendered - Diagrams professionally rendered
**Review Process:** **Review Process:**
- Technical review by external experts - Technical review by external experts
- Developmental editing - Developmental editing
- Copy editing - Copy editing
@ -117,6 +130,7 @@ Comprehensive publisher-specific requirements for technical book authors. This k
- Future-proof content when possible - Future-proof content when possible
### Resources ### Resources
- O'Reilly Atlas Platform: https://atlas.oreilly.com/ - O'Reilly Atlas Platform: https://atlas.oreilly.com/
- O'Reilly Author Resources: https://www.oreilly.com/work-with-us.html - O'Reilly Author Resources: https://www.oreilly.com/work-with-us.html
- Style guide provided to authors - Style guide provided to authors
@ -129,6 +143,7 @@ Comprehensive publisher-specific requirements for technical book authors. This k
### Manning Early Access Program (MEAP) ### Manning Early Access Program (MEAP)
**MEAP Overview:** **MEAP Overview:**
- Chapters published as completed - Chapters published as completed
- Reader feedback during writing process - Reader feedback during writing process
- Community engagement valued - Community engagement valued
@ -136,12 +151,14 @@ Comprehensive publisher-specific requirements for technical book authors. This k
- Chapters must stand alone (readers may not have earlier chapters) - Chapters must stand alone (readers may not have earlier chapters)
**Format:** **Format:**
- Microsoft Word or Markdown accepted - Microsoft Word or Markdown accepted
- Manning's production team handles final formatting - Manning's production team handles final formatting
- Author voice strongly encouraged - Author voice strongly encouraged
- Conversational tone valued - Conversational tone valued
**Style Guidelines:** **Style Guidelines:**
- Author personality and experience highlighted - Author personality and experience highlighted
- "We" or "I" voice appropriate - "We" or "I" voice appropriate
- Engaging, story-driven approach - Engaging, story-driven approach
@ -149,6 +166,7 @@ Comprehensive publisher-specific requirements for technical book authors. This k
- Humor and personality welcomed (within professional bounds) - Humor and personality welcomed (within professional bounds)
**Chapter Structure:** **Chapter Structure:**
- Context provided for standalone reading - Context provided for standalone reading
- Chapters in this chapter / Chapter summary - Chapters in this chapter / Chapter summary
- Margin notes or callouts for key points - Margin notes or callouts for key points
@ -156,6 +174,7 @@ Comprehensive publisher-specific requirements for technical book authors. This k
- Questions to engage readers - Questions to engage readers
**Code Examples:** **Code Examples:**
- GitHub repository required - GitHub repository required
- Code organized by chapter - Code organized by chapter
- README explains how to use examples - README explains how to use examples
@ -163,6 +182,7 @@ Comprehensive publisher-specific requirements for technical book authors. This k
- Version numbers specified - Version numbers specified
**Visual Elements:** **Visual Elements:**
- Diagrams enhance understanding - Diagrams enhance understanding
- Screenshots annotated helpfully - Screenshots annotated helpfully
- Manning's art team may redraw diagrams - Manning's art team may redraw diagrams
@ -179,6 +199,7 @@ Comprehensive publisher-specific requirements for technical book authors. This k
- Build community around your book - Build community around your book
### Resources ### Resources
- Manning Author Center: https://www.manning.com/write-for-us - Manning Author Center: https://www.manning.com/write-for-us
- MEAP author guidelines in contract - MEAP author guidelines in contract
- Developmental editor works closely with author - Developmental editor works closely with author
@ -191,12 +212,14 @@ Comprehensive publisher-specific requirements for technical book authors. This k
### Amazon Kindle Direct Publishing (KDP) ### Amazon Kindle Direct Publishing (KDP)
**Format:** **Format:**
- EPUB, MOBI, or Word formats - EPUB, MOBI, or Word formats
- Kindle Create tool available - Kindle Create tool available
- Preview tools for different devices - Preview tools for different devices
- DRM optional - DRM optional
**Requirements:** **Requirements:**
- Cover design (author provides or use KDP tools) - Cover design (author provides or use KDP tools)
- ISBN (Amazon provides free ASIN, or use your own ISBN) - ISBN (Amazon provides free ASIN, or use your own ISBN)
- Book description and keywords - Book description and keywords
@ -204,6 +227,7 @@ Comprehensive publisher-specific requirements for technical book authors. This k
- Pricing set by author (royalty tiers: 35% or 70%) - Pricing set by author (royalty tiers: 35% or 70%)
**Best Practices:** **Best Practices:**
- Mobile-friendly formatting essential - Mobile-friendly formatting essential
- Test on multiple Kindle devices/apps - Test on multiple Kindle devices/apps
- Table of contents with links - Table of contents with links
@ -213,12 +237,14 @@ Comprehensive publisher-specific requirements for technical book authors. This k
### Leanpub ### Leanpub
**Format:** **Format:**
- Markdown or direct writing in Leanpub editor - Markdown or direct writing in Leanpub editor
- Git integration available - Git integration available
- Automatic PDF, EPUB, MOBI generation - Automatic PDF, EPUB, MOBI generation
- Variable pricing model - Variable pricing model
**Unique Features:** **Unique Features:**
- Publish while writing (MVP approach) - Publish while writing (MVP approach)
- Reader feedback during writing - Reader feedback during writing
- Bundle options (book + code + videos) - Bundle options (book + code + videos)
@ -226,6 +252,7 @@ Comprehensive publisher-specific requirements for technical book authors. This k
- Coupons and promotional tools - Coupons and promotional tools
**Best Practices:** **Best Practices:**
- Minimum viable book to start (even a few chapters) - Minimum viable book to start (even a few chapters)
- Iterate based on reader feedback - Iterate based on reader feedback
- Keep readers updated with new content - Keep readers updated with new content
@ -233,6 +260,7 @@ Comprehensive publisher-specific requirements for technical book authors. This k
- Market directly to your audience - Market directly to your audience
### Resources ### Resources
- KDP: https://kdp.amazon.com - KDP: https://kdp.amazon.com
- Leanpub: https://leanpub.com - Leanpub: https://leanpub.com
- Gumroad for technical books: https://gumroad.com - Gumroad for technical books: https://gumroad.com
@ -243,23 +271,27 @@ Comprehensive publisher-specific requirements for technical book authors. This k
## General Publisher Considerations ## General Publisher Considerations
### Royalty Structures ### Royalty Structures
- Traditional publishers: 8-15% of net (after retailer cut) - Traditional publishers: 8-15% of net (after retailer cut)
- Self-publishing: 35-70% of gross (varies by platform) - Self-publishing: 35-70% of gross (varies by platform)
- Advance payments vary widely (technical books: $5K-$25K typical, can be much higher for established authors) - Advance payments vary widely (technical books: $5K-$25K typical, can be much higher for established authors)
### Rights and Licensing ### Rights and Licensing
- Traditional: publisher typically gets exclusive rights for term - Traditional: publisher typically gets exclusive rights for term
- Self-publishing: you retain all rights - Self-publishing: you retain all rights
- Code licensing: often separate from book copyright - Code licensing: often separate from book copyright
- Translation rights negotiable - Translation rights negotiable
### Marketing and Promotion ### Marketing and Promotion
- Traditional publisher provides some marketing, author expected to promote - Traditional publisher provides some marketing, author expected to promote
- Self-publishing: 100% author responsibility - Self-publishing: 100% author responsibility
- Author platform important for both (blog, social media, speaking) - Author platform important for both (blog, social media, speaking)
- Technical community engagement valuable - Technical community engagement valuable
### Timeline Considerations ### Timeline Considerations
- Traditional: 6-18 months from contract to publication - Traditional: 6-18 months from contract to publication
- Self-publishing: author controls timeline (can publish immediately or over time) - Self-publishing: author controls timeline (can publish immediately or over time)
- Both: writing typically takes 6-12 months for comprehensive book - Both: writing typically takes 6-12 months for comprehensive book
@ -269,6 +301,7 @@ Comprehensive publisher-specific requirements for technical book authors. This k
## Choosing the Right Publisher ## Choosing the Right Publisher
### Traditional Publisher When: ### Traditional Publisher When:
- You want professional editing and production - You want professional editing and production
- Marketing support desired - Marketing support desired
- Credibility and imprint important - Credibility and imprint important
@ -277,6 +310,7 @@ Comprehensive publisher-specific requirements for technical book authors. This k
- Don't want to manage production details - Don't want to manage production details
### Self-Publishing When: ### Self-Publishing When:
- You want full control - You want full control
- Higher per-book royalty important - Higher per-book royalty important
- Quick time to market needed - Quick time to market needed
@ -285,6 +319,7 @@ Comprehensive publisher-specific requirements for technical book authors. This k
- Willing to handle production and marketing - Willing to handle production and marketing
### Hybrid Approach: ### Hybrid Approach:
- Self-publish first to build audience - Self-publish first to build audience
- Traditional deal for expanded/updated version - Traditional deal for expanded/updated version
- Or reverse: traditional first, then self-publish later editions - Or reverse: traditional first, then self-publish later editions
@ -295,6 +330,7 @@ Comprehensive publisher-specific requirements for technical book authors. This k
## Submission Best Practices (All Publishers) ## Submission Best Practices (All Publishers)
### Proposal Elements ### Proposal Elements
- Book concept and unique value - Book concept and unique value
- Target audience definition - Target audience definition
- Competitive analysis - Competitive analysis
@ -305,6 +341,7 @@ Comprehensive publisher-specific requirements for technical book authors. This k
- Timeline estimate - Timeline estimate
### Professional Presentation ### Professional Presentation
- Well-formatted proposal - Well-formatted proposal
- Error-free writing - Error-free writing
- Realistic timeline - Realistic timeline
@ -312,6 +349,7 @@ Comprehensive publisher-specific requirements for technical book authors. This k
- Clear differentiators from competing books - Clear differentiators from competing books
### Building Relationships ### Building Relationships
- Network at conferences - Network at conferences
- Engage with publisher's community - Engage with publisher's community
- Follow editors on social media - Follow editors on social media
@ -323,22 +361,26 @@ Comprehensive publisher-specific requirements for technical book authors. This k
## Resources and References ## Resources and References
### Style Guides ### Style Guides
- Chicago Manual of Style: https://www.chicagomanualofstyle.org/ - Chicago Manual of Style: https://www.chicagomanualofstyle.org/
- Microsoft Writing Style Guide: https://docs.microsoft.com/en-us/style-guide/ - Microsoft Writing Style Guide: https://docs.microsoft.com/en-us/style-guide/
- Google Developer Documentation Style Guide: https://developers.google.com/style - Google Developer Documentation Style Guide: https://developers.google.com/style
### Author Communities ### Author Communities
- Write the Docs: https://www.writethedocs.org/ - Write the Docs: https://www.writethedocs.org/
- Technical Writer HQ: https://technicalwriterhq.com/ - Technical Writer HQ: https://technicalwriterhq.com/
- Author platforms (varies by publisher) - Author platforms (varies by publisher)
### Tools ### Tools
- Atlas (O'Reilly): https://atlas.oreilly.com/ - Atlas (O'Reilly): https://atlas.oreilly.com/
- Leanpub: https://leanpub.com - Leanpub: https://leanpub.com
- Kindle Create: https://kdp.amazon.com/en_US/help/topic/G202131100 - Kindle Create: https://kdp.amazon.com/en_US/help/topic/G202131100
- AsciiDoc: https://asciidoc.org/ - AsciiDoc: https://asciidoc.org/
### Legal and Rights ### Legal and Rights
- Authors Guild: https://www.authorsguild.org/ - Authors Guild: https://www.authorsguild.org/
- Contract review resources - Contract review resources
- Rights management tools - Rights management tools

51
expansion-packs/bmad-technical-writing/data/technical-writing-standards.md
View File

@ -7,11 +7,13 @@ Comprehensive standards for creating clear, consistent, accessible, and well-str
### Use Simple, Direct Language ### Use Simple, Direct Language
**Do:** **Do:**
- "Click the Submit button" (clear, direct) - "Click the Submit button" (clear, direct)
- "The function returns a boolean value" (precise) - "The function returns a boolean value" (precise)
- "Remove the file" (simple verb) - "Remove the file" (simple verb)
**Don't:** **Don't:**
- "Utilize the Submit functionality to initiate the process" (unnecessarily complex) - "Utilize the Submit functionality to initiate the process" (unnecessarily complex)
- "The function facilitates the return of a boolean-type value" (wordy) - "The function facilitates the return of a boolean-type value" (wordy)
- "Effect the removal of the file" (pretentious) - "Effect the removal of the file" (pretentious)
@ -19,6 +21,7 @@ Comprehensive standards for creating clear, consistent, accessible, and well-str
### Explain Technical Terms ### Explain Technical Terms
**First Use Pattern:** **First Use Pattern:**
``` ```
JSON (JavaScript Object Notation) is a lightweight data format... JSON (JavaScript Object Notation) is a lightweight data format...
[Later in text] [Later in text]
@ -26,11 +29,13 @@ JSON (JavaScript Object Notation) is a lightweight data format...
``` ```
**Inline Explanation:** **Inline Explanation:**
``` ```
The API returns a 401 status code, which indicates unauthorized access. The API returns a 401 status code, which indicates unauthorized access.
``` ```
**Glossary Reference:** **Glossary Reference:**
``` ```
The service uses OAuth2 for authentication (see Glossary). The service uses OAuth2 for authentication (see Glossary).
``` ```
@ -38,6 +43,7 @@ The service uses OAuth2 for authentication (see Glossary).
### Provide Examples ### Provide Examples
**Abstract Concept:** **Abstract Concept:**
``` ```
❌ "Functions should be idempotent." ❌ "Functions should be idempotent."
@ -45,6 +51,7 @@ The service uses OAuth2 for authentication (see Glossary).
``` ```
**Show, Then Tell:** **Show, Then Tell:**
```python ```python
# Example first # Example first
def calculate_total(items): def calculate_total(items):
@ -58,6 +65,7 @@ a Pythonic way to iterate and transform data in a single line.
### Break Down Complex Ideas ### Break Down Complex Ideas
**Step-by-Step:** **Step-by-Step:**
``` ```
To implement authentication: To implement authentication:
1. Create a User model with password hashing 1. Create a User model with password hashing
@ -69,6 +77,7 @@ To implement authentication:
``` ```
**Progressive Disclosure:** **Progressive Disclosure:**
- Start with simplest case - Start with simplest case
- Add complexity incrementally - Add complexity incrementally
- Reference advanced topics for later - Reference advanced topics for later
@ -76,22 +85,26 @@ To implement authentication:
### Active Voice ### Active Voice
**Prefer Active:** **Prefer Active:**
- "The function returns an array" (active) - "The function returns an array" (active)
- "Pass the parameter to the function" (active) - "Pass the parameter to the function" (active)
- "The compiler throws an error" (active) - "The compiler throws an error" (active)
**Avoid Passive:** **Avoid Passive:**
- "An array is returned by the function" (passive) - "An array is returned by the function" (passive)
- "The parameter should be passed to the function" (passive) - "The parameter should be passed to the function" (passive)
- "An error is thrown by the compiler" (passive) - "An error is thrown by the compiler" (passive)
**Exception:** Passive voice appropriate when actor is unknown or unimportant: **Exception:** Passive voice appropriate when actor is unknown or unimportant:
- "The file was corrupted" (we don't know who/what corrupted it) - "The file was corrupted" (we don't know who/what corrupted it)
- "Python was released in 1991" (focus on Python, not Guido) - "Python was released in 1991" (focus on Python, not Guido)
### Sentence Clarity ### Sentence Clarity
**One Idea Per Sentence:** **One Idea Per Sentence:**
``` ```
❌ "The function validates the input and then transforms it to the required format and returns it to the caller or throws an error if validation fails." ❌ "The function validates the input and then transforms it to the required format and returns it to the caller or throws an error if validation fails."
@ -99,6 +112,7 @@ To implement authentication:
``` ```
**Specific vs Vague:** **Specific vs Vague:**
``` ```
❌ "The database might have some issues with performance." ❌ "The database might have some issues with performance."
✓ "Query response time increases from 50ms to 2 seconds when the users table exceeds 1 million rows." ✓ "Query response time increases from 50ms to 2 seconds when the users table exceeds 1 million rows."
@ -111,12 +125,14 @@ To implement authentication:
### Terminology Consistency ### Terminology Consistency
**Choose One Term:** **Choose One Term:**
``` ```
✓ Consistent: "function" throughout ✓ Consistent: "function" throughout
❌ Inconsistent: "function", "method", "routine", "procedure" interchangeably ❌ Inconsistent: "function", "method", "routine", "procedure" interchangeably
``` ```
**Create a Term List:** **Create a Term List:**
``` ```
Preferred Terms: Preferred Terms:
- "filesystem" (not "file system") - "filesystem" (not "file system")
@ -129,6 +145,7 @@ Preferred Terms:
### Style Consistency ### Style Consistency
**Code Formatting:** **Code Formatting:**
``` ```
✓ Consistent: ✓ Consistent:
Use `variable_name` for variables and `function_name()` for functions. Use `variable_name` for variables and `function_name()` for functions.
@ -139,6 +156,7 @@ Use variable_name for variables and function_name() for functions.
``` ```
**Heading Capitalization:** **Heading Capitalization:**
``` ```
✓ Title Case Consistent: ✓ Title Case Consistent:
## Chapter 1: Building Your First API ## Chapter 1: Building Your First API
@ -158,6 +176,7 @@ Use variable_name for variables and function_name() for functions.
### Voice and Tone ### Voice and Tone
**Maintain Consistent Perspective:** **Maintain Consistent Perspective:**
``` ```
✓ Second Person Throughout: ✓ Second Person Throughout:
"You create a function by using the def keyword. You then add parameters..." "You create a function by using the def keyword. You then add parameters..."
@ -168,6 +187,7 @@ Use variable_name for variables and function_name() for functions.
``` ```
**Consistent Formality Level:** **Consistent Formality Level:**
- Casual: "Let's dive in!", "Cool!", "Pretty neat, right?" - Casual: "Let's dive in!", "Cool!", "Pretty neat, right?"
- Professional: "We'll begin", "Effective", "This demonstrates" - Professional: "We'll begin", "Effective", "This demonstrates"
- Pick one and maintain throughout - Pick one and maintain throughout
@ -175,6 +195,7 @@ Use variable_name for variables and function_name() for functions.
### Formatting Patterns ### Formatting Patterns
**Code Blocks:** **Code Blocks:**
``` ```
✓ Consistent: ✓ Consistent:
All code blocks use language tags and show complete context All code blocks use language tags and show complete context
@ -184,6 +205,7 @@ Some with language tags, some without; some show imports, some don't
``` ```
**Lists:** **Lists:**
``` ```
✓ Parallel Structure: ✓ Parallel Structure:
- Create the database - Create the database
@ -203,6 +225,7 @@ Some with language tags, some without; some show imports, some don't
### Alt Text for Images ### Alt Text for Images
**Descriptive Alt Text:** **Descriptive Alt Text:**
``` ```
❌ <img alt="screenshot"> ❌ <img alt="screenshot">
❌ <img alt="Figure 1"> ❌ <img alt="Figure 1">
@ -212,6 +235,7 @@ Some with language tags, some without; some show imports, some don't
``` ```
**Complex Diagrams:** **Complex Diagrams:**
``` ```
<img alt="Authentication flow diagram" longdesc="auth-flow-description.html"> <img alt="Authentication flow diagram" longdesc="auth-flow-description.html">
@ -225,6 +249,7 @@ this token in subsequent requests via the Authorization header..."
### Color and Visual Information ### Color and Visual Information
**Don't Rely on Color Alone:** **Don't Rely on Color Alone:**
``` ```
❌ "The red items are errors, green items are successes." ❌ "The red items are errors, green items are successes."
@ -232,6 +257,7 @@ this token in subsequent requests via the Authorization header..."
``` ```
**Code Syntax Highlighting:** **Code Syntax Highlighting:**
``` ```
# Ensure code is understandable without color # Ensure code is understandable without color
@ -245,6 +271,7 @@ api_key = "abc123xyz"
### Document Structure ### Document Structure
**Proper Heading Hierarchy:** **Proper Heading Hierarchy:**
``` ```
✓ Correct: ✓ Correct:
# Chapter 1: Introduction (H1) # Chapter 1: Introduction (H1)
@ -260,6 +287,7 @@ api_key = "abc123xyz"
``` ```
**Meaningful Headings:** **Meaningful Headings:**
``` ```
✓ Descriptive: "Installing PostgreSQL on macOS" ✓ Descriptive: "Installing PostgreSQL on macOS"
❌ Generic: "Installation" or "Next Steps" ❌ Generic: "Installation" or "Next Steps"
@ -268,6 +296,7 @@ api_key = "abc123xyz"
### Screen Reader Considerations ### Screen Reader Considerations
**Link Text:** **Link Text:**
``` ```
❌ "Click [here] to download Python." ❌ "Click [here] to download Python."
❌ "Learn more at [this link]." ❌ "Learn more at [this link]."
@ -277,6 +306,7 @@ api_key = "abc123xyz"
``` ```
**Table Structure:** **Table Structure:**
``` ```
| Header 1 | Header 2 | Header 3 | | Header 1 | Header 2 | Header 3 |
|----------|----------|----------| |----------|----------|----------|
@ -287,6 +317,7 @@ api_key = "abc123xyz"
``` ```
**Code Examples:** **Code Examples:**
```python ```python
# Use descriptive variable names that make sense when read aloud # Use descriptive variable names that make sense when read aloud
✓ user_email = "user@example.com" ✓ user_email = "user@example.com"
@ -300,6 +331,7 @@ api_key = "abc123xyz"
### Plain Language ### Plain Language
**Acronyms:** **Acronyms:**
``` ```
✓ "REST (Representational State Transfer) is an architectural style..." ✓ "REST (Representational State Transfer) is an architectural style..."
Later: "...using REST APIs..." Later: "...using REST APIs..."
@ -308,6 +340,7 @@ Later: "...using REST APIs..."
``` ```
**Define Jargon:** **Define Jargon:**
``` ```
✓ "Idempotent operations produce the same result when executed multiple times." ✓ "Idempotent operations produce the same result when executed multiple times."
❌ "Operations should be idempotent." (no explanation) ❌ "Operations should be idempotent." (no explanation)
@ -320,6 +353,7 @@ Later: "...using REST APIs..."
### Logical Topic Progression ### Logical Topic Progression
**Foundation First:** **Foundation First:**
``` ```
Chapter Sequence: Chapter Sequence:
1. Python Basics → 2. Functions → 3. Classes → 4. Advanced OOP 1. Python Basics → 2. Functions → 3. Classes → 4. Advanced OOP
@ -330,6 +364,7 @@ Chapter Sequence:
``` ```
**Dependency Management:** **Dependency Management:**
``` ```
✓ "In Chapter 2, we learned about functions. Now we'll use functions to..." ✓ "In Chapter 2, we learned about functions. Now we'll use functions to..."
✓ "This builds on the authentication system from Chapter 5..." ✓ "This builds on the authentication system from Chapter 5..."
@ -340,6 +375,7 @@ Chapter Sequence:
### Section Organization ### Section Organization
**Consistent Chapter Structure:** **Consistent Chapter Structure:**
``` ```
Chapter Template: Chapter Template:
1. Introduction (hooks, context, objectives) 1. Introduction (hooks, context, objectives)
@ -354,6 +390,7 @@ Use same structure for every chapter (readers know what to expect)
``` ```
**Section Length:** **Section Length:**
- Chapters: 15-30 pages typical - Chapters: 15-30 pages typical
- Major sections: 3-8 pages - Major sections: 3-8 pages
- Subsections: 1-3 pages - Subsections: 1-3 pages
@ -362,6 +399,7 @@ Use same structure for every chapter (readers know what to expect)
### Transitions ### Transitions
**Between Sections:** **Between Sections:**
``` ```
✓ "Now that you understand basic routing, let's add authentication to protect routes." ✓ "Now that you understand basic routing, let's add authentication to protect routes."
@ -371,6 +409,7 @@ Use same structure for every chapter (readers know what to expect)
``` ```
**Between Chapters:** **Between Chapters:**
``` ```
Chapter End: "In the next chapter, we'll deploy this application to production." Chapter End: "In the next chapter, we'll deploy this application to production."
@ -380,6 +419,7 @@ Next Chapter Start: "In Chapter 5, we built a REST API. Now we'll deploy it usin
### Cross-References ### Cross-References
**Specific References:** **Specific References:**
``` ```
✓ "See Chapter 3, Section 3.2: Database Setup" ✓ "See Chapter 3, Section 3.2: Database Setup"
✓ "As explained in the Authentication section on page 45..." ✓ "As explained in the Authentication section on page 45..."
@ -389,6 +429,7 @@ Next Chapter Start: "In Chapter 5, we built a REST API. Now we'll deploy it usin
``` ```
**Forward References:** **Forward References:**
``` ```
✓ "We'll cover error handling in depth in Chapter 8." ✓ "We'll cover error handling in depth in Chapter 8."
✓ "Advanced caching strategies are beyond this book's scope. See 'High Performance Python' by Gorelick and Ozsvald." ✓ "Advanced caching strategies are beyond this book's scope. See 'High Performance Python' by Gorelick and Ozsvald."
@ -399,6 +440,7 @@ Manage expectations about what's covered where
### Visual Hierarchy ### Visual Hierarchy
**Use Formatting:** **Use Formatting:**
- **Bold** for emphasis or key terms - **Bold** for emphasis or key terms
- `Code formatting` for inline code - `Code formatting` for inline code
- > Blockquotes for important callouts - > Blockquotes for important callouts
@ -406,6 +448,7 @@ Manage expectations about what's covered where
- Tables for structured data - Tables for structured data
**Consistent Callouts:** **Consistent Callouts:**
``` ```
**Note:** Additional information **Note:** Additional information
**Warning:** Potential pitfall **Warning:** Potential pitfall
@ -420,6 +463,7 @@ Manage expectations about what's covered where
### Code Comments ### Code Comments
**Explain Why, Not What:** **Explain Why, Not What:**
```python ```python
❌ # Set x to 5 ❌ # Set x to 5
x = 5 x = 5
@ -433,6 +477,7 @@ for attempt in range(max_retries):
``` ```
**Document Intent:** **Document Intent:**
```python ```python
✓ # Remove duplicates while preserving order ✓ # Remove duplicates while preserving order
seen = set() seen = set()
@ -447,6 +492,7 @@ for item in items:
### Function Documentation ### Function Documentation
**Docstring Standard:** **Docstring Standard:**
```python ```python
def authenticate_user(username, password): def authenticate_user(username, password):
""" """
@ -473,6 +519,7 @@ def authenticate_user(username, password):
### API Documentation ### API Documentation
**Endpoint Description:** **Endpoint Description:**
``` ```
GET /api/users/:id GET /api/users/:id
@ -502,22 +549,26 @@ Response 404:
## References and Resources ## References and Resources
### Style Guide Standards ### Style Guide Standards
- Microsoft Writing Style Guide - Microsoft Writing Style Guide
- Google Developer Documentation Style Guide - Google Developer Documentation Style Guide
- Chicago Manual of Style (for publishers) - Chicago Manual of Style (for publishers)
- AP Stylebook (for journalism-style technical writing) - AP Stylebook (for journalism-style technical writing)
### Accessibility Standards ### Accessibility Standards
- WCAG 2.1 Level AA (minimum) - WCAG 2.1 Level AA (minimum)
- Section 508 (US government) - Section 508 (US government)
- Plain Language guidelines - Plain Language guidelines
### Technical Writing Communities ### Technical Writing Communities
- Write the Docs: https://www.writethedocs.org/ - Write the Docs: https://www.writethedocs.org/
- TC (Technical Communication) Stack Exchange - TC (Technical Communication) Stack Exchange
- Reddit: r/technicalwriting - Reddit: r/technicalwriting
### Tools ### Tools
- Hemingway Editor (readability) - Hemingway Editor (readability)
- Grammarly (grammar and style) - Grammarly (grammar and style)
- Vale (style guide linter) - Vale (style guide linter)

450
expansion-packs/bmad-technical-writing/tasks/build-glossary.md Normal file
View File

@ -0,0 +1,450 @@
<!-- Powered by BMAD™ Core -->
# Build Glossary
---
task:
id: build-glossary
name: Build Glossary
description: Compile comprehensive glossary of technical terms with clear definitions
persona_default: api-documenter
inputs: - chapter-content or full manuscript - existing-glossary (if updating)
steps: - Extract technical terms from all chapters - Define each term clearly and concisely - Provide context where term is used - Add cross-references to related terms - Organize alphabetically - Verify accuracy of definitions - Check for consistency across book - Add first-use markers if required by publisher - Format per publisher requirements - Review for completeness - Run execute-checklist.md with glossary-accuracy-checklist.md
output: docs/glossary.md or Appendix: Glossary
---
## Purpose
This task guides you through creating a comprehensive, accurate glossary that helps readers quickly look up technical terms and concepts. The result is a reference resource that improves book usability and reader comprehension.
## Prerequisites
Before starting this task:
- Have chapter content available
- Access to technical-writing-standards.md knowledge base
- Know publisher's glossary requirements
- Have list of domain-specific terminology
## Workflow Steps
### 1. Extract Technical Terms
Identify terms that need definitions:
**Include:**
- Domain-specific technical terms (API, microservice, container)
- Framework/library-specific terms (React hooks, Django ORM)
- Acronyms and abbreviations (REST, CRUD, JWT)
- Jargon that may be unfamiliar (idempotent, immutable, memoization)
- Concepts central to the book (dependency injection, event sourcing)
- Tool or product names (Docker, Kubernetes, PostgreSQL)
**Exclude:**
- Common programming terms (if, loop, function) unless domain uses them uniquely
- General English words
- Terms used only once and explained inline
- Obvious concepts for target audience
**Extraction methods:**
**Manual extraction:**
- Read through each chapter
- Note terms that might confuse readers
- Mark terms used across multiple chapters
- Identify inconsistent terminology
**Pattern search:**
- Search for capitalized terms
- Find acronyms (all-caps words)
- Look for italicized or bolded terms
- Check code comments for technical terms
**First-use indicators:**
- Many books mark first use of glossary terms
- Look for italic or parenthetical definitions
- Note chapter where term first appears
### 2. Define Each Term Clearly
Write precise, concise definitions:
**Format:**
**Term (Pronunciation if non-obvious)**
_Part of speech_
Clear, concise definition in 1-3 sentences. Focus on what the term means in the context of this book's domain.
**Example used in this book:** Brief example or usage context.
**See also:** Related terms
---
**Examples:**
**API (Application Programming Interface)**
_noun_
A set of rules and protocols that define how software components communicate with each other. APIs expose specific functionality while hiding implementation details, enabling developers to use services without understanding their internal workings.
**Example used in this book:** In Chapter 5, you built a RESTful API that exposes endpoints for creating and retrieving user data.
**See also:** RESTful API, endpoint, HTTP methods
---
**Idempotent**
_adjective (eye-dem-POH-tent)_
A property of an operation where performing it multiple times has the same effect as performing it once. Idempotent operations are crucial for building reliable distributed systems that can safely retry failed requests.
**Example used in this book:** The PUT and DELETE HTTP methods are idempotent - sending the same PUT request twice produces the same final state.
**See also:** HTTP methods, RESTful API, side effects
---
**Guidelines:**
- Define in plain language first, then technical precision
- Avoid circular definitions ("X is a type of X that...")
- Use analogies if helpful ("like a telephone switchboard")
- Specify the context (database context vs. general programming)
- Keep definitions under 100 words
- Write for target audience's level
**Good vs. Bad:**
- ✅ "A container bundles an application with its dependencies into an isolated environment"
- ❌ "Containerization technology" (defines nothing)
- ✅ "JWT (JSON Web Token) is a compact, URL-safe token format for transmitting authentication claims between parties"
- ❌ "JWT is used for auth" (too vague)
### 3. Provide Context and Usage
Show where/how the term appears:
**Chapter reference:**
"First introduced in Chapter 3: Database Design"
**Usage context:**
"Used throughout Part II when discussing asynchronous operations"
**Code example:**
```python
# Example of idempotent operation
PUT /users/123 # Updates user 123 to specific state
PUT /users/123 # Repeated request produces same result
```
**Practical scenario:**
"When debugging container networking issues (Chapter 7), you'll use these commands to inspect bridge networks."
**Why context matters:**
- Helps readers find where concept is explained
- Connects definition to practical use
- Provides memory aid for later recall
### 4. Add Cross-References
Link related terms:
**Format:**
**See also:** Related term 1, Related term 2, Related term 3
**Types of relationships:**
**Broader/narrower:**
- "See also: HTTP methods (broader concept), GET, POST (specific methods)"
**Related concepts:**
- "See also: authentication, authorization, session management"
**Alternatives or contrasts:**
- "See also: SQL (contrast with), relational database"
**Prerequisites:**
- "See also: function, scope (required understanding)"
**Cross-reference guidelines:**
- 2-5 related terms maximum
- Order by relevance
- Link terms actually in glossary
- Use consistent term naming
### 5. Organize Alphabetically
Structure for easy lookup:
**Format:**
```
# Glossary
## A
**API (Application Programming Interface)**
...
**Asynchronous**
...
## B
**Backend**
...
**Bearer Token**
...
```
**Alphabetization rules:**
- Ignore "A", "An", "The" prefixes
- Acronyms alphabetize as single words (API comes before Application)
- Case-insensitive sorting
- Numbers spell out (2FA becomes "Two-factor authentication")
**Symbols and numbers:**
- Create separate "Symbols" or "Numbers" section
- Or integrate: "@ (at sign)", "# (hashtag)"
### 6. Verify Accuracy of Definitions
Validate each definition:
- [ ] Is the definition factually correct?
- [ ] Does it match how the term is used in the book?
- [ ] Is it appropriate for target audience?
- [ ] Have I avoided circular definitions?
- [ ] Are acronyms expanded correctly?
- [ ] Are examples accurate?
- [ ] Have I cited sources for external definitions?
**Validation methods:**
- Cross-check with authoritative sources (official docs, RFCs, standards)
- Verify against book content usage
- Have subject matter expert review
- Test definitions with target audience
**Common errors to fix:**
- Outdated definitions (old version of technology)
- Too narrow (only covers one use case)
- Too broad (loses specific meaning)
- Inconsistent with book usage
### 7. Check for Consistency Across Book
Ensure uniform terminology:
**Consistency checks:**
**Spelling variations:**
- "email" vs. "e-mail"
- "login" vs. "log in" vs. "log-in"
- "setup" (noun) vs. "set up" (verb)
**Terminology:**
- "function" vs. "method" (be precise)
- "argument" vs. "parameter"
- "client" vs. "user" vs. "caller"
**Capitalization:**
- "Internet" vs. "internet"
- "Boolean" vs. "boolean"
- "Web" vs. "web"
**Hyphenation:**
- "multi-tenant" vs. "multitenant"
- "open-source" vs. "open source"
**Process:**
1. List all variants of term usage
2. Choose canonical form
3. Define in glossary
4. Note variants if common
5. Update book chapters for consistency
**Example entry:**
**Log in** (verb), **login** (noun/adjective)
_verb:_ To authenticate and access a system by providing credentials.
_noun/adjective:_ The process or screen for authentication (e.g., "login page").
**Note:** This book uses "log in" as two words for the verb ("users log in") and "login" as one word for the noun ("the login failed").
### 8. Add First-Use Markers
If required by publisher:
**Techniques:**
**In-text marker:**
First occurrence of term in chapter is italicized or bolded:
"The _application programming interface_ (API) defines..."
**Footnote reference:**
"The API³ defines..."
³ See glossary
**Parenthetical:**
"The API (see glossary) defines..."
**Publisher-specific requirements:**
- PacktPub: Italic on first use per chapter
- O'Reilly: Bold on first use, no special marker
- Manning: Italic with index entry
- Self-publish: Choose consistent approach
### 9. Format Per Publisher Requirements
Apply publisher formatting:
**Standard format:**
```markdown
# Glossary
**Term**
Definition text here.
**Another term**
Definition text here.
```
**With categorization (if required):**
```markdown
# Glossary
## Core Concepts
...
## Tools and Technologies
...
## HTTP and Networking
...
```
**With pronunciation (if needed):**
```markdown
**Kubernetes** (koo-ber-NET-eez)
```
**With etymology (optional):**
```markdown
**Idempotent** (from Latin _idem_ "same" + _potent_ "power")
```
**Publisher-specific:**
- Check style guide
- Follow existing book examples
- Match formatting conventions
### 10. Review for Completeness
Final validation:
- [ ] All chapter-specific terms included?
- [ ] All acronyms expanded?
- [ ] Cross-references accurate?
- [ ] Definitions clear and concise?
- [ ] Alphabetization correct?
- [ ] Consistent terminology throughout?
- [ ] Publisher requirements met?
- [ ] Target audience appropriate?
**Completeness check:**
- Read random chapter section
- Note unfamiliar terms
- Verify they're in glossary
- If not, add them
### 11. Run Glossary Accuracy Checklist
Validate using checklist:
- glossary-accuracy-checklist.md - Ensure all terms defined, accurate, and consistent
## Success Criteria
A completed glossary should have:
- [ ] All technical terms from book included
- [ ] Clear, concise definitions (1-3 sentences each)
- [ ] Usage context or examples provided
- [ ] Cross-references to related terms
- [ ] Alphabetical organization
- [ ] Definitions verified for accuracy
- [ ] Consistent terminology across book
- [ ] First-use markers (if required)
- [ ] Publisher formatting applied
- [ ] Glossary accuracy checklist passed
## Common Pitfalls to Avoid
- **Incomplete coverage**: Missing terms readers might not know
- **Circular definitions**: Defining term using itself
- **Too technical**: Definitions harder to understand than term
- **Inconsistent usage**: Term defined differently than used in book
- **Missing acronym expansions**: "JWT" without "JSON Web Token"
- **No context**: Definition without usage example
- **Outdated definitions**: Not reflecting current version of technology
- **Poor organization**: Difficult to find terms
## Notes and Warnings
- **Living document**: Update glossary as chapters evolve
- **Consistency is key**: Glossary should match book content exactly
- **Target audience matters**: Beginner book needs more terms defined
- **Cross-references add value**: Help readers understand relationships
- **Examples clarify**: Usage context makes definitions concrete
- **Verify accuracy**: Incorrect definitions erode trust
- **Publisher requirements**: Check style guide early
## Next Steps
After building glossary:
1. Review with technical editor for accuracy
2. Check consistency with main content
3. Add to appendix or back matter
4. Create index entries for glossary terms (if separate index exists)
5. Update as new terms added in revisions
6. Consider adding glossary terms to book index

58
expansion-packs/bmad-technical-writing/tasks/copy-edit-chapter.md
View File

@ -5,29 +5,13 @@
--- ---
task: task:
id: copy-edit-chapter id: copy-edit-chapter
name: Copy Edit Chapter name: Copy Edit Chapter
description: Professional editorial polish including grammar, clarity, consistency, style compliance, and accessibility description: Professional editorial polish including grammar, clarity, consistency, style compliance, and accessibility
persona_default: technical-editor persona_default: technical-editor
inputs: inputs: - chapter-draft - chapter-number - target-publisher
- chapter-draft steps: - Review chapter for grammar and spelling - Check terminology consistency throughout - Verify publisher style guide compliance - Improve sentence clarity and readability - Enhance transitions between sections - Check heading hierarchy and structure - Verify code formatting consistency - Review accessibility considerations - Polish language for professional quality - Ensure consistent voice and tone - Create summary of editorial changes - Run execute-checklist.md with accessibility-checklist.md - Run execute-checklist.md with relevant publisher checklist
- chapter-number output: Edited chapter with change summary
- target-publisher
steps:
- Review chapter for grammar and spelling
- Check terminology consistency throughout
- Verify publisher style guide compliance
- Improve sentence clarity and readability
- Enhance transitions between sections
- Check heading hierarchy and structure
- Verify code formatting consistency
- Review accessibility considerations
- Polish language for professional quality
- Ensure consistent voice and tone
- Create summary of editorial changes
- Run execute-checklist.md with accessibility-checklist.md
- Run execute-checklist.md with relevant publisher checklist
output: Edited chapter with change summary
--- ---
@ -50,6 +34,7 @@ Transform technically accurate content into professionally polished, publication
Perform comprehensive language check: Perform comprehensive language check:
**Grammar:** **Grammar:**
- Subject-verb agreement - Subject-verb agreement
- Pronoun references - Pronoun references
- Verb tenses (use present tense for technical writing) - Verb tenses (use present tense for technical writing)
@ -57,11 +42,13 @@ Perform comprehensive language check:
- Sentence fragments and run-ons - Sentence fragments and run-ons
**Spelling:** **Spelling:**
- Technical terms spelled correctly - Technical terms spelled correctly
- Consistent spelling (US vs UK English) - Consistent spelling (US vs UK English)
- Common technical term errors (e.g., "GitHub" not "Github") - Common technical term errors (e.g., "GitHub" not "Github")
**Tools:** **Tools:**
- Use spell checker as first pass - Use spell checker as first pass
- Manual review for technical terms - Manual review for technical terms
- Verify proper nouns and product names - Verify proper nouns and product names
@ -73,12 +60,14 @@ Perform comprehensive language check:
Ensure terms used consistently throughout: Ensure terms used consistently throughout:
**Term Standardization:** **Term Standardization:**
- Create term list for chapter - Create term list for chapter
- Use same term for same concept (not "function" then "method" interchangeably) - Use same term for same concept (not "function" then "method" interchangeably)
- Match terminology to official documentation - Match terminology to official documentation
- Consistent capitalization (e.g., "JavaScript" not "Javascript") - Consistent capitalization (e.g., "JavaScript" not "Javascript")
**Common Inconsistencies:** **Common Inconsistencies:**
- API vs API's vs APIs (plurals and possessives) - API vs API's vs APIs (plurals and possessives)
- Filename vs file name vs file-name - Filename vs file name vs file-name
- Setup vs set up (noun vs verb) - Setup vs set up (noun vs verb)
@ -91,6 +80,7 @@ Ensure terms used consistently throughout:
Apply specific publisher requirements: Apply specific publisher requirements:
**PacktPub:** **PacktPub:**
- Chicago Manual of Style - Chicago Manual of Style
- Second person ("you") perspective - Second person ("you") perspective
- Active voice preferred - Active voice preferred
@ -98,18 +88,21 @@ Apply specific publisher requirements:
- Screenshots at required resolution - Screenshots at required resolution
**O'Reilly:** **O'Reilly:**
- Chicago Manual of Style - Chicago Manual of Style
- Specific heading levels - Specific heading levels
- Code highlighting conventions - Code highlighting conventions
- Cross-reference formatting - Cross-reference formatting
**Manning:** **Manning:**
- Conversational but professional tone - Conversational but professional tone
- Author voice encouraged - Author voice encouraged
- Specific formatting for code listings - Specific formatting for code listings
- Margin note requirements - Margin note requirements
**Use relevant checklist:** **Use relevant checklist:**
- packtpub-submission-checklist.md - packtpub-submission-checklist.md
- oreilly-format-checklist.md - oreilly-format-checklist.md
- manning-meap-checklist.md - manning-meap-checklist.md
@ -119,6 +112,7 @@ Apply specific publisher requirements:
Enhance readability and comprehension: Enhance readability and comprehension:
**Clarity Principles:** **Clarity Principles:**
- One idea per sentence when possible - One idea per sentence when possible
- Active voice preferred over passive - Active voice preferred over passive
- Remove unnecessary words - Remove unnecessary words
@ -130,12 +124,14 @@ Enhance readability and comprehension:
**After:** "This pattern often improves performance." **After:** "This pattern often improves performance."
**Avoid:** **Avoid:**
- Jargon without explanation - Jargon without explanation
- Overly complex sentence structures - Overly complex sentence structures
- Ambiguous pronouns ("it", "this", "that" without clear referent) - Ambiguous pronouns ("it", "this", "that" without clear referent)
- Double negatives - Double negatives
**Preserve:** **Preserve:**
- Author voice and style - Author voice and style
- Technical precision - Technical precision
- Necessary complexity - Necessary complexity
@ -145,17 +141,20 @@ Enhance readability and comprehension:
Improve flow between sections and ideas: Improve flow between sections and ideas:
**Between Sections:** **Between Sections:**
- Add transition sentences linking topics - Add transition sentences linking topics
- Preview what's coming next - Preview what's coming next
- Reference what was just covered - Reference what was just covered
- Explain logical progression - Explain logical progression
**Example Transitions:** **Example Transitions:**
- "Now that you understand X, let's explore Y..." - "Now that you understand X, let's explore Y..."
- "With this foundation in place, we can tackle..." - "With this foundation in place, we can tackle..."
- "Building on the previous example, you'll now..." - "Building on the previous example, you'll now..."
**Within Paragraphs:** **Within Paragraphs:**
- Use transition words (however, therefore, additionally) - Use transition words (however, therefore, additionally)
- Maintain logical flow - Maintain logical flow
- Connect sentences coherently - Connect sentences coherently
@ -167,18 +166,21 @@ Improve flow between sections and ideas:
Ensure proper document structure: Ensure proper document structure:
**Hierarchy Rules:** **Hierarchy Rules:**
- H1: Chapter title (one per chapter) - H1: Chapter title (one per chapter)
- H2: Major sections - H2: Major sections
- H3: Subsections - H3: Subsections
- H4: Minor subsections (use sparingly) - H4: Minor subsections (use sparingly)
**Heading Best Practices:** **Heading Best Practices:**
- Parallel structure in same level - Parallel structure in same level
- Descriptive and specific - Descriptive and specific
- Avoid "Introduction" as H2 (use descriptive title) - Avoid "Introduction" as H2 (use descriptive title)
- Capitalize consistently - Capitalize consistently
**Example:** **Example:**
``` ```
# Chapter 3: Database Design (H1) # Chapter 3: Database Design (H1)
## Understanding Relational Databases (H2) ## Understanding Relational Databases (H2)
@ -193,23 +195,27 @@ Ensure proper document structure:
Ensure all code formatted properly: Ensure all code formatted properly:
**Code Blocks:** **Code Blocks:**
- Language specified for syntax highlighting - Language specified for syntax highlighting
- Consistent indentation (spaces vs tabs) - Consistent indentation (spaces vs tabs)
- Line length appropriate (avoid horizontal scrolling) - Line length appropriate (avoid horizontal scrolling)
- Comments formatted consistently - Comments formatted consistently
**Inline Code:** **Inline Code:**
- Use backticks for code terms - Use backticks for code terms
- Function names: `function_name()` - Function names: `function_name()`
- Variables: `variable_name` - Variables: `variable_name`
- File paths: `path/to/file.py` - File paths: `path/to/file.py`
**Code Callouts:** **Code Callouts:**
- Explanations below code blocks - Explanations below code blocks
- Reference specific lines when needed - Reference specific lines when needed
- Expected output shown where relevant - Expected output shown where relevant
**Consistency:** **Consistency:**
- Same style throughout chapter - Same style throughout chapter
- Matches publisher requirements - Matches publisher requirements
- Follows language conventions - Follows language conventions
@ -221,6 +227,7 @@ Ensure content is accessible to all readers:
**Use accessibility-checklist.md** **Use accessibility-checklist.md**
**Key Checks:** **Key Checks:**
- Alt text for all images and diagrams - Alt text for all images and diagrams
- Color not the sole means of conveying information - Color not the sole means of conveying information
- Code examples screen-reader friendly - Code examples screen-reader friendly
@ -236,18 +243,21 @@ Ensure content is accessible to all readers:
Final pass for professional quality: Final pass for professional quality:
**Voice and Tone:** **Voice and Tone:**
- Consistent throughout chapter - Consistent throughout chapter
- Appropriate for audience (not too casual, not too formal) - Appropriate for audience (not too casual, not too formal)
- Encouraging and supportive (avoid condescending) - Encouraging and supportive (avoid condescending)
- Technical but approachable - Technical but approachable
**Readability:** **Readability:**
- Vary sentence length - Vary sentence length
- Break up long paragraphs (3-5 sentences typical) - Break up long paragraphs (3-5 sentences typical)
- Use lists for multiple items - Use lists for multiple items
- Add white space for visual breaks - Add white space for visual breaks
**Professional Polish:** **Professional Polish:**
- Remove filler words (basically, simply, just) - Remove filler words (basically, simply, just)
- Strengthen weak verbs (use specific action verbs) - Strengthen weak verbs (use specific action verbs)
- Replace vague terms with specific ones - Replace vague terms with specific ones
@ -258,6 +268,7 @@ Final pass for professional quality:
Document editorial modifications: Document editorial modifications:
**Change Log Should Include:** **Change Log Should Include:**
- Major structural changes - Major structural changes
- Terminology standardizations - Terminology standardizations
- Sections rewritten for clarity - Sections rewritten for clarity
@ -265,6 +276,7 @@ Document editorial modifications:
- Accessibility improvements - Accessibility improvements
**Format:** **Format:**
``` ```
Editorial Changes Summary - Chapter 3 Editorial Changes Summary - Chapter 3

349
expansion-packs/bmad-technical-writing/tasks/create-diagram-spec.md Normal file
View File

@ -0,0 +1,349 @@
<!-- Powered by BMAD™ Core -->
# Create Diagram Specification
---
task:
id: create-diagram-spec
name: Create Diagram Specification
description: Design technical diagram specifications for visual documentation
persona_default: screenshot-specialist
inputs: - concept or process to visualize - chapter-section where diagram will appear - target-audience
steps: - Identify concept or process that needs visualization - Choose appropriate diagram type (flowchart, sequence, architecture, etc.) - List all key elements and components - Define relationships and flows between elements - Plan labels and annotations - Specify style requirements (colors, shapes, etc.) - Write alternative text description for accessibility - Define size and format requirements - Review for clarity and completeness - Validate diagram supports text explanation - Use template diagram-spec-tmpl.yaml with create-doc.md task - Run execute-checklist.md with diagram-clarity-checklist.md
output: docs/diagrams/{{diagram_id}}-spec.md
---
## Purpose
This task guides you through creating comprehensive diagram specifications that visual designers or diagram tools can use to create clear, effective technical diagrams. The result is a complete specification that ensures diagrams clarify concepts and meet accessibility standards.
## Prerequisites
Before starting this task:
- Have clear understanding of concept to visualize
- Know where diagram will appear in book
- Access to technical-writing-standards.md knowledge base
- Understand target audience's technical level
## Workflow Steps
### 1. Identify Concept to Visualize
Determine what needs a diagram:
- Complex process or workflow
- System architecture or components
- Data flow or transformation
- Decision tree or algorithm
- Timeline or sequence
- Comparison or relationship
**Ask:**
- What concept is hard to explain with text alone?
- Where do readers get confused?
- What mental model are you building?
- Would a visual clarify this immediately?
### 2. Choose Diagram Type
Select the most effective diagram type:
**Process/Flow Diagrams:**
- **Flowchart**: Decision trees, algorithms, step-by-step processes
- Use for: Control flow, decision logic, sequential processes
- **Sequence diagram**: Interactions over time, API calls, message passing
- Use for: Time-based interactions, protocol flows, object communication
- **Activity diagram**: Workflows, user journeys, parallel processes
- Use for: Complex workflows, concurrent activities, swimlane responsibilities
- **Data flow diagram**: Data movement through systems
- Use for: Data transformations, ETL processes, information flow
**Structure Diagrams:**
- **Architecture diagram**: System components and relationships
- Use for: High-level system design, microservices, deployment
- **Class diagram**: Object-oriented design, relationships
- Use for: Code structure, inheritance, composition
- **Entity-relationship diagram**: Database schemas
- Use for: Data models, database design, relationships
- **Component diagram**: Software architecture
- Use for: Module dependencies, package structure, interfaces
**Other:**
- **State diagram**: State machines, lifecycle
- Use for: Object states, transitions, event-driven behavior
- **Network diagram**: Infrastructure, deployment topology
- Use for: Server architecture, network topology, cloud resources
- **Timeline**: Historical progression, versioning
- Use for: Evolution of technology, release history, migration paths
**Selection criteria:**
- What type best represents this concept?
- What conventions will readers recognize?
- What tools are available for creation?
### 3. List Key Elements
Identify all components that must appear:
**Actors/Entities:**
- Users, systems, services
- External integrations
- Data stores
**Processes/Functions:**
- Operations, transformations
- Business logic, calculations
- API calls, functions
**Data:**
- Databases, caches, files
- Messages, requests, responses
- Configuration, state
**Control:**
- Decision points (if/else, switch)
- Loops (for, while)
- Error handlers, fallbacks
- Start and end points
For each element, specify:
- Name/label text
- Shape or symbol (rectangle, circle, diamond, etc.)
- Color or styling (if it conveys meaning)
- Size relative to other elements
### 4. Define Relationships and Flows
Map how elements connect:
**Connection types:**
- Solid arrow: Direct flow, data transfer, control flow
- Dashed arrow: Indirect relationship, optional flow
- Bidirectional arrow: Two-way communication
- No arrow (line only): Association, grouping
For each connection:
- Start and end points
- Direction of flow
- Sequence or order (number steps if needed)
- Conditions or triggers
- Labels (what's flowing: data type, message, protocol)
**Example:**
"User → (HTTP POST) → API Gateway → (JWT validation) → Auth Service → (SQL query) → Database → (AuthToken) → User"
### 5. Plan Labels and Annotations
Specify all text elements:
**Element labels:**
- Keep concise (2-4 words max)
- Use consistent terminology
- Match glossary terms
**Edge labels:**
- Data types (JSON, XML, binary)
- Protocols (HTTP, WebSocket, gRPC)
- Methods (GET, POST, publish, subscribe)
- Conditions ("if authenticated", "on error")
**Callout boxes:**
- Important notes that don't fit in main flow
- Timing information ("~200ms")
- Error conditions
- External constraints
**Step numbers:**
- For sequential processes
- Match numbered steps in text if applicable
**Legend:**
- Define special symbols
- Explain color coding
- Clarify line types
Keep labels brief - detailed explanation belongs in body text.
### 6. Specify Style Requirements
Define visual styling:
**Color scheme:**
- Consistent with other book diagrams
- Sufficient contrast for accessibility (WCAG AA: 4.5:1 for text)
- Meaningful use (green=success, red=error, blue=external system)
- Consider grayscale printing
**Shape conventions:**
- Rectangles: Processes, operations
- Rounded rectangles: Start/end points
- Diamonds: Decisions
- Cylinders: Databases
- Clouds: External services
- Stick figures: Actors
**Line styles:**
- Solid: Primary flow
- Dashed: Secondary or optional
- Dotted: Boundary or grouping
- Bold: Critical path
**Typography:**
- Font family (consistent with book)
- Minimum font size (10-12pt for readability)
- Bold for emphasis
- Monospace for code/variables
**Layout:**
- Left-to-right, top-to-bottom flow (Western reading)
- Adequate spacing (no cramming)
- Alignment and grid structure
- Balanced composition
### 7. Define Size and Format Requirements
Specify technical requirements:
**Dimensions:**
- Width × height (pixels for digital, inches for print)
- Aspect ratio
- Margins and padding
**Resolution:**
- 300 DPI minimum for print
- 150 DPI acceptable for web
- Vector format preferred (SVG, PDF)
**File format:**
- SVG: Scalable, best for web and print
- PNG: Raster with transparency
- PDF: Vector, preserves fonts
- Format depends on publisher requirements
**Placement:**
- Full page landscape
- Half page inline
- Wrap with text
- Facing page reference
### 8. Write Alternative Text Description
Create complete alt text for accessibility:
**Include:**
- Diagram purpose and context
- Main flow or structure
- Key components listed
- Important relationships
- Outcome or end state
**Example:**
"Sequence diagram showing OAuth2 authentication flow: User initiates login at web app. Web app redirects to OAuth provider. User enters credentials at OAuth provider. OAuth provider validates credentials and returns authorization code to web app. Web app exchanges code for access token. User is now authenticated with access token stored."
Alt text should enable someone who can't see the diagram to understand the concept.
**Guidelines:**
- Describe diagram type first
- Follow the flow logically
- Mention all critical elements
- Keep it concise but complete (100-200 words)
- Avoid "This diagram shows..." (screen readers already say "image")
### 9. Review for Clarity
Validate the specification:
- [ ] Does every element have a purpose?
- [ ] Are labels clear and concise?
- [ ] Is the flow easy to follow?
- [ ] Will this clarify the text explanation?
- [ ] Is complexity appropriate for audience?
- [ ] Is a legend needed?
- [ ] Does it meet accessibility standards?
### 10. Generate Diagram Specification
Use the create-doc.md task with diagram-spec-tmpl.yaml template to create the structured diagram specification document.
### 11. Validate with Checklist
Run checklist:
- diagram-clarity-checklist.md - Ensure diagram will be clear and effective
## Success Criteria
Completed diagram specification should have:
- [ ] Clear purpose and context defined
- [ ] Appropriate diagram type selected
- [ ] All elements listed with labels
- [ ] Relationships and flows defined
- [ ] Style requirements specified
- [ ] Size and format requirements defined
- [ ] Complete alternative text written
- [ ] Accessibility requirements met
- [ ] Clarity checklist passed
- [ ] Sufficient detail for designer/tool to create diagram
## Common Pitfalls to Avoid
- **Too complex**: Simplify, split into multiple diagrams if needed
- **Illegible labels**: Text too small or colors too similar
- **Missing legend**: Don't assume readers know your symbols
- **Poor flow direction**: Arrows should guide eye naturally
- **Inconsistent styling**: Use same shapes/colors for same concepts
- **No alt text**: Accessibility is required, not optional
- **Overcrowded**: Leave white space, don't cram everything in
- **Unclear purpose**: Diagram should clarify one specific concept
## Notes and Warnings
- **Accessibility is mandatory**: Alt text and color contrast are not optional
- **Test in grayscale**: Ensure diagram works without color
- **Keep it simple**: One diagram = one concept
- **Follow conventions**: Don't invent new symbol meanings
- **High resolution**: Low-res diagrams look unprofessional in print
- **Version control**: Maintain source files (not just rendered images)
## Next Steps
After creating diagram specification:
1. Create diagram using design tool or diagram software
2. Review rendered diagram against specification
3. Validate alt text accurately describes final diagram
4. Test accessibility (color contrast, screen reader)
5. Insert into chapter with figure number and caption
6. Reference diagram in body text ("see Figure 3.2")

64
expansion-packs/bmad-technical-writing/tasks/design-exercises.md
View File

@ -5,28 +5,13 @@
--- ---
task: task:
id: design-exercises id: design-exercises
name: Design Exercises name: Design Exercises
description: Create practice exercises with progressive difficulty, hints, and solution approaches description: Create practice exercises with progressive difficulty, hints, and solution approaches
persona_default: instructional-designer persona_default: instructional-designer
inputs: inputs: - chapter-number - learning-objectives - difficulty-range
- chapter-number steps: - Identify learning objectives to assess - Determine appropriate difficulty levels (basic to advanced) - Create 4-6 exercises per chapter with progressive difficulty - Progress from basic application to challenging problems - Write clear instructions for each exercise - Develop solution approaches (not full solutions) - Add progressive hints for learners - Create extension challenges for advanced students - Estimate completion time for each exercise - Validate exercises are solvable and appropriate - Run execute-checklist.md with exercise-difficulty-checklist.md - Use template exercise-set-tmpl.yaml with create-doc.md
- learning-objectives output: exercises/chapter-{{chapter_number}}-exercises.md
- difficulty-range
steps:
- Identify learning objectives to assess
- Determine appropriate difficulty levels (basic to advanced)
- Create 4-6 exercises per chapter with progressive difficulty
- Progress from basic application to challenging problems
- Write clear instructions for each exercise
- Develop solution approaches (not full solutions)
- Add progressive hints for learners
- Create extension challenges for advanced students
- Estimate completion time for each exercise
- Validate exercises are solvable and appropriate
- Run execute-checklist.md with exercise-difficulty-checklist.md
- Use template exercise-set-tmpl.yaml with create-doc.md
output: exercises/chapter-{{chapter_number}}-exercises.md
--- ---
@ -48,11 +33,13 @@ Create practice exercises that reinforce learning, assess comprehension, and bui
Map exercises to specific learning goals: Map exercises to specific learning goals:
**For Each Learning Objective:** **For Each Learning Objective:**
- Which exercises will assess this? - Which exercises will assess this?
- What demonstrates mastery? - What demonstrates mastery?
- How can students practice this skill? - How can students practice this skill?
**Example Mapping:** **Example Mapping:**
``` ```
Objective: "Implement JWT authentication" Objective: "Implement JWT authentication"
→ Exercise 2: Build login endpoint (basic) → Exercise 2: Build login endpoint (basic)
@ -61,6 +48,7 @@ Objective: "Implement JWT authentication"
``` ```
**Coverage:** **Coverage:**
- Each objective addressed by at least one exercise - Each objective addressed by at least one exercise
- Core objectives get multiple exercises - Core objectives get multiple exercises
- Progressive difficulty across related exercises - Progressive difficulty across related exercises
@ -70,18 +58,21 @@ Objective: "Implement JWT authentication"
Plan difficulty range appropriate for chapter: Plan difficulty range appropriate for chapter:
**Basic (⭐):** **Basic (⭐):**
- Direct application of chapter examples - Direct application of chapter examples
- Clear guidance and hints - Clear guidance and hints
- Builds confidence - Builds confidence
- 2-3 exercises per chapter - 2-3 exercises per chapter
**Intermediate (⭐⭐):** **Intermediate (⭐⭐):**
- Combines multiple concepts - Combines multiple concepts
- Requires problem-solving - Requires problem-solving
- Less hand-holding - Less hand-holding
- 1-2 exercises per chapter - 1-2 exercises per chapter
**Advanced (⭐⭐⭐):** **Advanced (⭐⭐⭐):**
- Creative application - Creative application
- Minimal guidance - Minimal guidance
- Extension of concepts - Extension of concepts
@ -96,19 +87,22 @@ Design exercise sequence:
**Exercise Structure:** **Exercise Structure:**
**Exercise Header:** **Exercise Header:**
- Number and title - Number and title
- Difficulty indicator (⭐ ⭐⭐ ⭐⭐⭐) - Difficulty indicator (⭐ ⭐⭐ ⭐⭐⭐)
- Estimated time - Estimated time
- Learning objective addressed - Learning objective addressed
**Problem Description:** **Problem Description:**
- Clear problem statement - Clear problem statement
- Specific requirements (numbered list) - Specific requirements (numbered list)
- Input/output examples - Input/output examples
- Success criteria - Success criteria
**Example:** **Example:**
```
````
### Exercise 3: User Input Validation ⭐⭐ ### Exercise 3: User Input Validation ⭐⭐
**Estimated Time:** 20 minutes **Estimated Time:** 20 minutes
**Learning Objective:** Apply regex for validation **Learning Objective:** Apply regex for validation
@ -129,13 +123,15 @@ validate_user_input("user123", "user@example.com", "Pass123!")
validate_user_input("ab", "invalid", "weak") validate_user_input("ab", "invalid", "weak")
# Returns: {"username": False, "email": False, "password": False, "valid": False} # Returns: {"username": False, "email": False, "password": False, "valid": False}
``` ````
**Success Criteria:** **Success Criteria:**
- All test cases pass - All test cases pass
- Clear error messages for invalid inputs - Clear error messages for invalid inputs
- Uses regex for email validation - Uses regex for email validation
```
````
### 4. Write Clear Instructions ### 4. Write Clear Instructions
@ -170,19 +166,21 @@ def validate_user_input(username, email, password):
""" """
# Your code here # Your code here
pass pass
``` ````
### 5. Develop Solution Approaches ### 5. Develop Solution Approaches
Provide guidance without giving away the answer: Provide guidance without giving away the answer:
**Solution Approach (Not Full Code):** **Solution Approach (Not Full Code):**
- High-level algorithm - High-level algorithm
- Key concepts to apply - Key concepts to apply
- Recommended data structures - Recommended data structures
- Common pitfalls to avoid - Common pitfalls to avoid
**Example:** **Example:**
``` ```
**Solution Approach:** **Solution Approach:**
1. Create validation functions for each field type 1. Create validation functions for each field type
@ -209,11 +207,13 @@ Provide guidance without giving away the answer:
Create hints that reveal information gradually: Create hints that reveal information gradually:
**Hint Structure:** **Hint Structure:**
- Hint 1: General approach or concept - Hint 1: General approach or concept
- Hint 2: More specific technique - Hint 2: More specific technique
- Hint 3: Nearly complete solution approach - Hint 3: Nearly complete solution approach
**Example:** **Example:**
``` ```
**Hints:** **Hints:**
1. Break the problem into three separate validation functions 1. Break the problem into three separate validation functions
@ -224,6 +224,7 @@ Create hints that reveal information gradually:
``` ```
**Good Hints:** **Good Hints:**
- Guide thinking, don't solve the problem - Guide thinking, don't solve the problem
- Progressive reveal (start general) - Progressive reveal (start general)
- Specific to common sticking points - Specific to common sticking points
@ -234,13 +235,15 @@ Create hints that reveal information gradually:
Add optional advanced problems: Add optional advanced problems:
**Extension Characteristics:** **Extension Characteristics:**
- Builds on basic exercise - Builds on basic exercise
- Requires creative thinking - Requires creative thinking
- No hints provided - No hints provided
- Tests deeper mastery - Tests deeper mastery
**Example Extensions:** **Example Extensions:**
```
````
**Extension Challenges:** **Extension Challenges:**
**Challenge 1: Password Strength Meter** **Challenge 1: Password Strength Meter**
@ -257,7 +260,8 @@ rules = {
"password": {"min": 12, "require_special": True, "require_number": True} "password": {"min": 12, "require_special": True, "require_number": True}
} }
validate_with_rules(data, rules) validate_with_rules(data, rules)
``` ````
``` ```
**Purpose:** Challenges extend learning for students who want more practice. **Purpose:** Challenges extend learning for students who want more practice.
@ -283,12 +287,15 @@ Provide realistic time estimates:
**State in Exercise:** **State in Exercise:**
``` ```
**Estimated Time:** 25 minutes **Estimated Time:** 25 minutes
This includes: This includes:
- Understanding requirements: 5 min - Understanding requirements: 5 min
- Implementation: 15 min - Implementation: 15 min
- Testing: 5 min - Testing: 5 min
``` ```
### 9. Validate Exercises Are Solvable ### 9. Validate Exercises Are Solvable
@ -381,3 +388,4 @@ After designing exercises:
4. Iterate based on feedback 4. Iterate based on feedback
5. Update hints if students commonly stuck 5. Update hints if students commonly stuck
6. Consider creating video solutions for complex exercises 6. Consider creating video solutions for complex exercises
```

66
expansion-packs/bmad-technical-writing/tasks/develop-tutorial.md
View File

@ -5,28 +5,13 @@
--- ---
task: task:
id: develop-tutorial id: develop-tutorial
name: Develop Tutorial name: Develop Tutorial
description: Create hands-on step-by-step tutorial with tested code, clear instructions, and troubleshooting description: Create hands-on step-by-step tutorial with tested code, clear instructions, and troubleshooting
persona_default: tutorial-architect persona_default: tutorial-architect
inputs: inputs: - tutorial-topic - learning-objective - difficulty-level
- tutorial-topic steps: - Identify specific learning objective for tutorial - Define prerequisite knowledge and setup requirements - Design step-by-step progression (8-15 steps typical) - Write clear, actionable instructions for each step - Create and test code examples for each step - Document expected outputs at each step - Add troubleshooting section for common issues - Test complete tutorial end-to-end - Verify progressive difficulty and skill building - Include summary and next steps - Run execute-checklist.md with tutorial-effectiveness-checklist.md - Use template tutorial-section-tmpl.yaml with create-doc.md
- learning-objective output: tutorials/{{tutorial-slug}}.md
- difficulty-level
steps:
- Identify specific learning objective for tutorial
- Define prerequisite knowledge and setup requirements
- Design step-by-step progression (8-15 steps typical)
- Write clear, actionable instructions for each step
- Create and test code examples for each step
- Document expected outputs at each step
- Add troubleshooting section for common issues
- Test complete tutorial end-to-end
- Verify progressive difficulty and skill building
- Include summary and next steps
- Run execute-checklist.md with tutorial-effectiveness-checklist.md
- Use template tutorial-section-tmpl.yaml with create-doc.md
output: tutorials/{{tutorial-slug}}.md
--- ---
@ -48,15 +33,18 @@ Create effective hands-on tutorials that guide learners through building somethi
Define what students will accomplish: Define what students will accomplish:
**Specific and Measurable:** **Specific and Measurable:**
- "Build a REST API with authentication" (good) - "Build a REST API with authentication" (good)
- "Learn about APIs" (too vague) - "Learn about APIs" (too vague)
**Achievable Scope:** **Achievable Scope:**
- 30-45 minutes for basic tutorials - 30-45 minutes for basic tutorials
- 1-2 hours for intermediate - 1-2 hours for intermediate
- 2-4 hours for advanced - 2-4 hours for advanced
**Clear Success Criteria:** **Clear Success Criteria:**
- What will work at the end? - What will work at the end?
- What skills will be demonstrated? - What skills will be demonstrated?
- What can student verify? - What can student verify?
@ -66,21 +54,25 @@ Define what students will accomplish:
Be explicit about requirements: Be explicit about requirements:
**Knowledge Prerequisites:** **Knowledge Prerequisites:**
- "Understanding of Python functions and classes" - "Understanding of Python functions and classes"
- "Completed Tutorial 2: Flask Basics" - "Completed Tutorial 2: Flask Basics"
- "Familiarity with HTTP request/response cycle" - "Familiarity with HTTP request/response cycle"
**Software Requirements:** **Software Requirements:**
- "Python 3.11+" - "Python 3.11+"
- "PostgreSQL 15+ running locally" - "PostgreSQL 15+ running locally"
- "VS Code or similar editor" - "VS Code or similar editor"
**Setup Steps:** **Setup Steps:**
- "Clone starter repository" - "Clone starter repository"
- "Create virtual environment" - "Create virtual environment"
- "Install dependencies: `pip install -r requirements.txt`" - "Install dependencies: `pip install -r requirements.txt`"
**Time Estimates:** **Time Estimates:**
- Setup time: 10 minutes - Setup time: 10 minutes
- Tutorial time: 45 minutes - Tutorial time: 45 minutes
- Total: ~1 hour - Total: ~1 hour
@ -90,6 +82,7 @@ Be explicit about requirements:
Plan the tutorial flow (typically 8-15 steps): Plan the tutorial flow (typically 8-15 steps):
**Logical Progression:** **Logical Progression:**
1. Setup and initialization 1. Setup and initialization
2. Core concept introduction 2. Core concept introduction
3. Basic implementation 3. Basic implementation
@ -100,12 +93,14 @@ Plan the tutorial flow (typically 8-15 steps):
8. Summary/reflection 8. Summary/reflection
**Each Step Should:** **Each Step Should:**
- Build on previous steps - Build on previous steps
- Accomplish one clear goal - Accomplish one clear goal
- Be testable/verifiable - Be testable/verifiable
- Take 3-8 minutes - Take 3-8 minutes
**Progressive Difficulty:** **Progressive Difficulty:**
- Start simple (foundational) - Start simple (foundational)
- Add complexity gradually - Add complexity gradually
- End with realistic scenario - End with realistic scenario
@ -115,7 +110,8 @@ Plan the tutorial flow (typically 8-15 steps):
Use consistent, actionable format: Use consistent, actionable format:
**Step Format:** **Step Format:**
```
````
**Step N: [Action-Oriented Title]** **Step N: [Action-Oriented Title]**
[Brief explanation of what this step accomplishes] [Brief explanation of what this step accomplishes]
@ -128,9 +124,10 @@ Use consistent, actionable format:
**Code:** **Code:**
```language ```language
[Complete code to add/modify] [Complete code to add/modify]
``` ````
**Expected Output:** **Expected Output:**
``` ```
[What student should see] [What student should see]
``` ```
@ -140,6 +137,7 @@ Use consistent, actionable format:
**Verification:** **Verification:**
[How to confirm this step worked] [How to confirm this step worked]
``` ```
**Imperative Voice:** **Imperative Voice:**
@ -179,12 +177,15 @@ Show what success looks like:
**After Key Steps:** **After Key Steps:**
``` ```
After Step 3, running `python app.py` should display: After Step 3, running `python app.py` should display:
* Running on http://127.0.0.1:5000
* Debug mode: on - Running on http://127.0.0.1:5000
- Debug mode: on
Visiting http://localhost:5000/health should return: Visiting http://localhost:5000/health should return:
{"status": "healthy", "timestamp": "2024-01-15T10:30:00Z"} {"status": "healthy", "timestamp": "2024-01-15T10:30:00Z"}
``` ```
**Screenshots (where helpful):** **Screenshots (where helpful):**
@ -195,15 +196,17 @@ Visiting http://localhost:5000/health should return:
**File Structure:** **File Structure:**
``` ```
After Step 5, your project should look like: After Step 5, your project should look like:
tutorial-app/ tutorial-app/
├── app.py ├── app.py
├── models/ ├── models/
│ └── user.py │ └── user.py
├── routes/ ├── routes/
│ └── auth.py │ └── auth.py
└── tests/ └── tests/
└── test_auth.py └── test_auth.py
``` ```
### 7. Add Troubleshooting Section ### 7. Add Troubleshooting Section
@ -224,20 +227,24 @@ Anticipate and solve common problems:
**Example:** **Example:**
``` ```
**Problem:** ImportError: No module named 'flask' **Problem:** ImportError: No module named 'flask'
**Cause:** Flask not installed or wrong Python environment **Cause:** Flask not installed or wrong Python environment
**Diagnosis:** **Diagnosis:**
1. Check virtual environment activated: `which python` 1. Check virtual environment activated: `which python`
2. Check installed packages: `pip list | grep -i flask` 2. Check installed packages: `pip list | grep -i flask`
**Fix:** **Fix:**
1. Activate virtual environment: `source venv/bin/activate` 1. Activate virtual environment: `source venv/bin/activate`
2. Install Flask: `pip install flask` 2. Install Flask: `pip install flask`
3. Verify: `python -c "import flask; print(flask.__version__)"` 3. Verify: `python -c "import flask; print(flask.__version__)"`
**Verification:** Re-run your app - should start without import errors **Verification:** Re-run your app - should start without import errors
``` ```
**Include 3-5 most common issues** based on typical student mistakes. **Include 3-5 most common issues** based on typical student mistakes.
@ -364,3 +371,4 @@ After creating tutorial:
3. Test with target audience if possible 3. Test with target audience if possible
4. Gather feedback and iterate 4. Gather feedback and iterate
5. Update based on common student questions 5. Update based on common student questions
```

262
expansion-packs/bmad-technical-writing/tasks/generate-api-docs.md Normal file
View File

@ -0,0 +1,262 @@
<!-- Powered by BMAD™ Core -->
# Generate API Documentation
---
task:
id: generate-api-docs
name: Generate API Documentation
description: Create comprehensive API reference documentation with parameters, return values, and usage examples
persona_default: api-documenter
inputs: - api-component (function, class, module, or API endpoint) - source-code or API specification - target-audience (developers using this API)
steps: - Identify all API components that need documentation - Extract function/method signatures from source code or spec - Document all parameters with types, descriptions, and constraints - Document return values with types and descriptions - Document exceptions and error conditions - Create 2-3 realistic usage examples for each API - Add cross-references to related APIs - Create parameter and return value tables - Validate examples work correctly - Format per publisher requirements - Use template api-reference-tmpl.yaml with create-doc.md task - Run execute-checklist.md with glossary-accuracy-checklist.md
output: docs/api-reference/{{api_name}}-reference.md
---
## Purpose
This task guides you through creating complete, accurate API reference documentation that developers can trust. The result is comprehensive reference material structured for quick lookup.
## Prerequisites
Before starting this task:
- Have access to source code or API specifications
- Know the target audience's technical level
- Have working code examples to validate
- Access to code-style-guides.md knowledge base
## Workflow Steps
### 1. Identify API Components
Determine what needs documentation:
- Individual functions or methods
- Classes and their members
- Modules or packages
- RESTful API endpoints
- Configuration options
- Data structures
Create a comprehensive list of all components.
### 2. Extract Signatures
For each API component, extract:
- Full function/method signature
- Import path or package location
- Version introduced (if applicable)
- Deprecation status (if applicable)
**Example:**
```python
def authenticate_user(username: str, password: str, remember_me: bool = False) -> AuthToken
```
### 3. Document Parameters
Create a complete parameter table:
| Parameter | Type | Required | Default | Description |
| ----------- | ---- | -------- | ------- | ---------------------------------- |
| username | str | Yes | - | User's login username (3-50 chars) |
| password | str | Yes | - | User's password (min 8 chars) |
| remember_me | bool | No | False | Keep user logged in beyond session |
For each parameter:
- Exact name as it appears in code
- Type annotation (be precise)
- Required or Optional
- Default value if optional
- Clear, concise description
- Valid ranges or constraints
- Examples of valid values
### 4. Document Return Values
Specify what the API returns:
- Return type (include None/null if possible)
- Description of returned value
- Structure of complex return objects
- Examples of return values
- Conditions that affect return value
**Example:**
```
Returns: AuthToken object containing JWT token (str) and expiration timestamp (datetime)
Returns None if authentication fails
```
### 5. Document Exceptions and Errors
List all possible errors:
| Exception/Error | Condition | How to Handle |
| ------------------- | ----------------------------------------- | ---------------------------------- |
| ValueError | Username/password empty or invalid format | Validate input before calling |
| AuthenticationError | Invalid credentials | Show error to user, allow retry |
| NetworkError | Auth service unavailable | Implement retry logic with backoff |
For each exception:
- Exception class name or error code
- What triggers this exception
- How to prevent or handle it
- Impact on application state
### 6. Create Usage Examples
Provide 2-3 realistic code examples:
**Example 1: Basic usage (most common case)**
```python
# Authenticate with username and password
token = authenticate_user("john_doe", "secure_password")
if token:
print(f"Login successful, token expires: {token.expires_at}")
```
**Example 2: Advanced usage (with optional parameters)**
```python
# Authenticate with persistent session
token = authenticate_user(
username="john_doe",
password="secure_password",
remember_me=True
)
```
**Example 3: Error handling (production-ready)**
```python
# Proper error handling
try:
token = authenticate_user(username, password)
if token is None:
print("Invalid credentials")
else:
# Proceed with authenticated session
pass
except ValueError as e:
print(f"Invalid input: {e}")
except AuthenticationError as e:
print(f"Auth failed: {e}")
```
Ensure:
- Examples are realistic and practical
- Code is tested and works correctly
- Examples demonstrate best practices
- Error handling is shown where appropriate
### 7. Add Cross-References
Link to related functionality:
- Functions that work together
- Alternative approaches
- Required setup functions (e.g., initialize_auth_service())
- Functions that consume this API's output
- Relevant chapter sections
**Example:**
"See also: `refresh_token()` for renewing expired tokens, `logout_user()` for ending sessions, Chapter 5: Authentication Architecture"
### 8. Create Reference Tables
For complex APIs, create summary tables:
**Authentication API Methods:**
| Method | Purpose | Returns |
|--------|---------|---------|
| authenticate_user() | Login with credentials | AuthToken |
| refresh_token() | Renew expired token | AuthToken |
| validate_token() | Check token validity | bool |
| logout_user() | End session | None |
### 9. Validate Examples
Ensure all code examples:
- [ ] Actually run without errors
- [ ] Use correct imports
- [ ] Follow project code style
- [ ] Demonstrate real-world usage
- [ ] Handle errors appropriately
- [ ] Work with current API version
Run examples in test environment to verify.
### 10. Format for Publisher
Apply publisher-specific formatting:
- **PacktPub**: Markdown with clear code blocks
- **O'Reilly**: AsciiDoc if required
- **Manning**: Code listings with callouts
- **Self-publish**: Clean markdown with syntax highlighting
### 11. Generate Documentation
Use the create-doc.md task with api-reference-tmpl.yaml template to create the structured API documentation.
### 12. Validate Terminology
Run checklist:
- glossary-accuracy-checklist.md - Ensure consistent terminology
## Success Criteria
Completed API documentation should have:
- [ ] All API components documented
- [ ] Complete parameter tables with types and descriptions
- [ ] Return values documented with types
- [ ] All exceptions and errors listed
- [ ] 2-3 working code examples per API
- [ ] Cross-references to related APIs
- [ ] Examples validated and tested
- [ ] Publisher formatting applied
- [ ] Terminology consistent with glossary
- [ ] Searchable structure (clear headings, tables)
## Common Pitfalls to Avoid
- **Incomplete parameter docs**: Every parameter needs type, description, constraints
- **Missing error cases**: Document all exceptions, not just happy path
- **Untested examples**: Always run examples to verify they work
- **Vague descriptions**: "Authenticates user" is too vague; be specific
- **No cross-references**: Link related APIs together
- **Inconsistent terminology**: Use same terms as glossary and main text
- **Missing edge cases**: Document behavior with null/None, empty strings, etc.
## Notes and Warnings
- **Type precision**: Use exact type annotations from code
- **Version compatibility**: Note if API changed between versions
- **Performance**: Document O(n) complexity if relevant
- **Thread safety**: Note if API is thread-safe or not
- **Platform differences**: Document platform-specific behavior
- **Security**: Warn about security implications (password handling, etc.)
## Next Steps
After generating API documentation:
1. Review with developers who use the API
2. Add to appendix or API reference chapter
3. Keep synchronized with code changes
4. Update glossary with new terms
5. Link from main chapter text to API reference

56
expansion-packs/bmad-technical-writing/tasks/technical-review-chapter.md
View File

@ -5,31 +5,13 @@
--- ---
task: task:
id: technical-review-chapter id: technical-review-chapter
name: Technical Review Chapter name: Technical Review Chapter
description: Comprehensive technical accuracy review with fact-checking, code validation, security audit, and best practices assessment description: Comprehensive technical accuracy review with fact-checking, code validation, security audit, and best practices assessment
persona_default: technical-reviewer persona_default: technical-reviewer
inputs: inputs: - chapter-draft - chapter-number - subject-area-expertise
- chapter-draft steps: - Read chapter draft completely for overview - Verify technical accuracy against official documentation - Review all code examples for correctness and best practices - Test code examples to ensure they run properly - Check for security vulnerabilities in code - Assess performance implications of recommendations - Identify outdated information or deprecated features - Note factual errors or misconceptions - Compile findings into structured review report - Assign severity levels to issues (Critical/Major/Minor) - Provide constructive recommendations with sources - Run execute-checklist.md with technical-accuracy-checklist.md - Run execute-checklist.md with security-best-practices-checklist.md - Run execute-checklist.md with performance-considerations-checklist.md - Use template technical-review-report-tmpl.yaml with create-doc.md
- chapter-number output: reviews/technical-review-chapter-{{chapter_number}}.md
- subject-area-expertise
steps:
- Read chapter draft completely for overview
- Verify technical accuracy against official documentation
- Review all code examples for correctness and best practices
- Test code examples to ensure they run properly
- Check for security vulnerabilities in code
- Assess performance implications of recommendations
- Identify outdated information or deprecated features
- Note factual errors or misconceptions
- Compile findings into structured review report
- Assign severity levels to issues (Critical/Major/Minor)
- Provide constructive recommendations with sources
- Run execute-checklist.md with technical-accuracy-checklist.md
- Run execute-checklist.md with security-best-practices-checklist.md
- Run execute-checklist.md with performance-considerations-checklist.md
- Use template technical-review-report-tmpl.yaml with create-doc.md
output: reviews/technical-review-chapter-{{chapter_number}}.md
--- ---
@ -64,12 +46,14 @@ Get the full context before detailed review:
Check all technical claims against authoritative sources: Check all technical claims against authoritative sources:
**For Each Technical Claim:** **For Each Technical Claim:**
- Is this factually correct? - Is this factually correct?
- Is it current (not outdated)? - Is it current (not outdated)?
- Can it be verified in official documentation? - Can it be verified in official documentation?
- Are version numbers specified correctly? - Are version numbers specified correctly?
**Sources to Check:** **Sources to Check:**
- Official language documentation (Python.org, MDN, etc.) - Official language documentation (Python.org, MDN, etc.)
- Framework official docs - Framework official docs
- RFCs and standards specifications - RFCs and standards specifications
@ -77,6 +61,7 @@ Check all technical claims against authoritative sources:
- Release notes - Release notes
**Document Issues:** **Document Issues:**
- Location (section, page, paragraph) - Location (section, page, paragraph)
- Incorrect statement - Incorrect statement
- Correct information - Correct information
@ -92,18 +77,21 @@ Validate all code in the chapter:
**For Each Code Example:** **For Each Code Example:**
**Syntax and Logic:** **Syntax and Logic:**
- Does the code have syntax errors? - Does the code have syntax errors?
- Will it run as shown? - Will it run as shown?
- Does it produce the claimed results? - Does it produce the claimed results?
- Are there logic errors? - Are there logic errors?
**Completeness:** **Completeness:**
- Are all imports shown? - Are all imports shown?
- Are dependencies clear? - Are dependencies clear?
- Is setup code included or explained? - Is setup code included or explained?
- Can a reader actually run this? - Can a reader actually run this?
**Accuracy:** **Accuracy:**
- Does the code use APIs correctly? - Does the code use APIs correctly?
- Are parameters in the right order? - Are parameters in the right order?
- Are return types correct? - Are return types correct?
@ -116,6 +104,7 @@ Validate all code in the chapter:
Assess whether code follows current best practices: Assess whether code follows current best practices:
**Code Quality:** **Code Quality:**
- Follows language style guides (PEP 8, ESLint, etc.) - Follows language style guides (PEP 8, ESLint, etc.)
- Uses meaningful variable names - Uses meaningful variable names
- Includes appropriate comments - Includes appropriate comments
@ -123,12 +112,14 @@ Assess whether code follows current best practices:
- Handles errors properly - Handles errors properly
**Design Patterns:** **Design Patterns:**
- Uses appropriate patterns - Uses appropriate patterns
- Avoids anti-patterns - Avoids anti-patterns
- Demonstrates scalable approaches - Demonstrates scalable approaches
- Shows proper separation of concerns - Shows proper separation of concerns
**Modern Approaches:** **Modern Approaches:**
- Uses current language features - Uses current language features
- Leverages modern libraries - Leverages modern libraries
- Follows framework conventions - Follows framework conventions
@ -141,6 +132,7 @@ Assess whether code follows current best practices:
Review for security vulnerabilities: Review for security vulnerabilities:
**Critical Issues:** **Critical Issues:**
- Hardcoded credentials or API keys - Hardcoded credentials or API keys
- SQL injection vulnerabilities - SQL injection vulnerabilities
- XSS (Cross-Site Scripting) risks - XSS (Cross-Site Scripting) risks
@ -149,6 +141,7 @@ Review for security vulnerabilities:
- Unsafe deserialization - Unsafe deserialization
**Best Practices:** **Best Practices:**
- HTTPS/TLS usage - HTTPS/TLS usage
- Password hashing (bcrypt, Argon2) - Password hashing (bcrypt, Argon2)
- JWT secret management - JWT secret management
@ -157,6 +150,7 @@ Review for security vulnerabilities:
- Principle of least privilege - Principle of least privilege
**For Each Security Issue:** **For Each Security Issue:**
- Describe the vulnerability - Describe the vulnerability
- Explain potential impact - Explain potential impact
- Provide secure code example - Provide secure code example
@ -170,6 +164,7 @@ Review for security vulnerabilities:
Consider performance and scalability: Consider performance and scalability:
**Inefficiencies:** **Inefficiencies:**
- O(n²) algorithms where O(n) is possible - O(n²) algorithms where O(n) is possible
- N+1 query problems - N+1 query problems
- Missing database indexes - Missing database indexes
@ -177,12 +172,14 @@ Consider performance and scalability:
- Memory leaks or excessive allocation - Memory leaks or excessive allocation
**Scalability:** **Scalability:**
- Will this approach scale to production? - Will this approach scale to production?
- Are there resource constraints? - Are there resource constraints?
- Is caching appropriate? - Is caching appropriate?
- Are there blocking operations in async code? - Are there blocking operations in async code?
**Recommendations:** **Recommendations:**
- Better algorithms or data structures - Better algorithms or data structures
- Optimization techniques - Optimization techniques
- Profiling suggestions - Profiling suggestions
@ -195,16 +192,19 @@ Consider performance and scalability:
Check currency of all technical content: Check currency of all technical content:
**Deprecated Features:** **Deprecated Features:**
- Language features no longer recommended - Language features no longer recommended
- Framework APIs deprecated - Framework APIs deprecated
- Tools superseded by newer alternatives - Tools superseded by newer alternatives
**Version Issues:** **Version Issues:**
- Library versions outdated or EOL - Library versions outdated or EOL
- Examples using old syntax - Examples using old syntax
- Missing modern alternatives - Missing modern alternatives
**Update Recommendations:** **Update Recommendations:**
- Current best practices - Current best practices
- Modern equivalents - Modern equivalents
- Migration paths - Migration paths
@ -219,6 +219,7 @@ Create structured technical review report:
**Use template:** technical-review-report-tmpl.yaml **Use template:** technical-review-report-tmpl.yaml
**Report Sections:** **Report Sections:**
- Executive summary (overall assessment) - Executive summary (overall assessment)
- Technical accuracy findings - Technical accuracy findings
- Code quality issues - Code quality issues
@ -230,6 +231,7 @@ Create structured technical review report:
- Prioritized recommendations - Prioritized recommendations
**Assign Severity:** **Assign Severity:**
- **Critical:** Must fix (factual errors, security issues, broken code) - **Critical:** Must fix (factual errors, security issues, broken code)
- **Major:** Should fix (best practice violations, performance issues) - **Major:** Should fix (best practice violations, performance issues)
- **Minor:** Nice to fix (style improvements, optimization suggestions) - **Minor:** Nice to fix (style improvements, optimization suggestions)
@ -239,6 +241,7 @@ Create structured technical review report:
For each issue, provide actionable guidance: For each issue, provide actionable guidance:
**Good Feedback Format:** **Good Feedback Format:**
``` ```
Location: Section 2.3, page 12, code example Location: Section 2.3, page 12, code example
Issue: Using `collections.MutableMapping` which is deprecated Issue: Using `collections.MutableMapping` which is deprecated
@ -252,12 +255,14 @@ class MyDict(MutableMapping):
``` ```
**Be Constructive:** **Be Constructive:**
- Explain why it's wrong - Explain why it's wrong
- Show how to fix it - Show how to fix it
- Provide source reference - Provide source reference
- Offer example code where helpful - Offer example code where helpful
**Avoid:** **Avoid:**
- Vague criticism ("this is bad") - Vague criticism ("this is bad")
- Nitpicking without explaining why - Nitpicking without explaining why
- Rewriting the entire chapter - Rewriting the entire chapter
@ -268,6 +273,7 @@ class MyDict(MutableMapping):
Validate against standard checklists: Validate against standard checklists:
**Execute:** **Execute:**
- technical-accuracy-checklist.md - technical-accuracy-checklist.md
- security-best-practices-checklist.md - security-best-practices-checklist.md
- performance-considerations-checklist.md - performance-considerations-checklist.md

57
expansion-packs/bmad-technical-writing/tasks/write-chapter-draft.md
View File

@ -5,27 +5,13 @@
--- ---
task: task:
id: write-chapter-draft id: write-chapter-draft
name: Write Chapter Draft name: Write Chapter Draft
description: Develop complete chapter manuscript from outline with introduction, main content, code examples, and exercises description: Develop complete chapter manuscript from outline with introduction, main content, code examples, and exercises
persona_default: tutorial-architect persona_default: tutorial-architect
inputs: inputs: - chapter-outline - learning-objectives - target-page-count
- chapter-outline steps: - Review chapter outline for structure and objectives - Write compelling introduction (hook, context, overview, prerequisites) - Draft main content sections (concept → tutorial → examples progression) - Create and test all code examples inline - Develop practice exercises with progressive difficulty - Write chapter summary with key takeaways - Add cross-references to other chapters and resources - Include further reading references - Verify all learning objectives are addressed - Run execute-checklist.md with chapter-completeness-checklist.md - Use template chapter-draft-tmpl.yaml with create-doc.md task
- learning-objectives output: docs/chapters/chapter-{{chapter_number}}-draft.md
- target-page-count
steps:
- Review chapter outline for structure and objectives
- Write compelling introduction (hook, context, overview, prerequisites)
- Draft main content sections (concept → tutorial → examples progression)
- Create and test all code examples inline
- Develop practice exercises with progressive difficulty
- Write chapter summary with key takeaways
- Add cross-references to other chapters and resources
- Include further reading references
- Verify all learning objectives are addressed
- Run execute-checklist.md with chapter-completeness-checklist.md
- Use template chapter-draft-tmpl.yaml with create-doc.md task
output: docs/chapters/chapter-{{chapter_number}}-draft.md
--- ---
@ -64,29 +50,34 @@ Create a compelling chapter opening that hooks readers and sets expectations.
**Introduction Components:** **Introduction Components:**
**Hook (1-2 paragraphs):** **Hook (1-2 paragraphs):**
- Start with a real-world problem or relatable scenario - Start with a real-world problem or relatable scenario
- Make readers care about learning this content - Make readers care about learning this content
- Use questions, stories, or surprising facts - Use questions, stories, or surprising facts
- Connect to reader pain points or aspirations - Connect to reader pain points or aspirations
**Context (1-2 paragraphs):** **Context (1-2 paragraphs):**
- Explain why this topic matters - Explain why this topic matters
- Industry relevance and use cases - Industry relevance and use cases
- How it fits in the bigger technical picture - How it fits in the bigger technical picture
- Connection to previous chapters - Connection to previous chapters
**Overview (1 paragraph):** **Overview (1 paragraph):**
- What will be covered in this chapter - What will be covered in this chapter
- High-level learning path - High-level learning path
- What readers will build or accomplish - What readers will build or accomplish
**Prerequisites:** **Prerequisites:**
- Previous chapters required - Previous chapters required
- Assumed knowledge - Assumed knowledge
- Software/tools needed with versions - Software/tools needed with versions
- Estimated time commitment - Estimated time commitment
**Learning Objectives:** **Learning Objectives:**
- 3-5 specific, measurable outcomes - 3-5 specific, measurable outcomes
- Use action verbs (implement, analyze, create, debug) - Use action verbs (implement, analyze, create, debug)
- Align with Bloom's taxonomy - Align with Bloom's taxonomy
@ -100,12 +91,14 @@ For each major section (typically 3-5 sections per chapter):
**Section Structure Pattern:** **Section Structure Pattern:**
**a) Concept Introduction** **a) Concept Introduction**
- Explain the concept clearly and concisely - Explain the concept clearly and concisely
- Use analogies or real-world comparisons where helpful - Use analogies or real-world comparisons where helpful
- Define technical terms - Define technical terms
- Provide theoretical background without overwhelming - Provide theoretical background without overwhelming
**b) Tutorial/Walkthrough** **b) Tutorial/Walkthrough**
- Step-by-step hands-on implementation - Step-by-step hands-on implementation
- Clear, numbered steps - Clear, numbered steps
- Imperative voice ("Create...", "Add...", "Run...") - Imperative voice ("Create...", "Add...", "Run...")
@ -113,6 +106,7 @@ For each major section (typically 3-5 sections per chapter):
- Explain what each step accomplishes and why - Explain what each step accomplishes and why
**c) Code Examples** **c) Code Examples**
- Complete, runnable code (not fragments unless explained) - Complete, runnable code (not fragments unless explained)
- Inline comments explaining key lines - Inline comments explaining key lines
- Best practices demonstrated - Best practices demonstrated
@ -120,6 +114,7 @@ For each major section (typically 3-5 sections per chapter):
- Input/output examples showing expected results - Input/output examples showing expected results
**d) Section Practice** **d) Section Practice**
- Mini-exercises reinforcing section concepts - Mini-exercises reinforcing section concepts
- Quick validation of understanding - Quick validation of understanding
- Progressive difficulty within section - Progressive difficulty within section
@ -133,6 +128,7 @@ For each major section (typically 3-5 sections per chapter):
Develop all code examples referenced in the chapter: Develop all code examples referenced in the chapter:
**Code Quality Standards:** **Code Quality Standards:**
- All code must be tested and run successfully - All code must be tested and run successfully
- Follow language-specific style guides - Follow language-specific style guides
- Include proper error handling - Include proper error handling
@ -141,6 +137,7 @@ Develop all code examples referenced in the chapter:
- Specify language version compatibility - Specify language version compatibility
**Code Presentation:** **Code Presentation:**
- Use proper syntax highlighting (specify language) - Use proper syntax highlighting (specify language)
- Show complete context (imports, setup, etc.) - Show complete context (imports, setup, etc.)
- Provide expected output or results - Provide expected output or results
@ -148,6 +145,7 @@ Develop all code examples referenced in the chapter:
- Reference code files in repository structure - Reference code files in repository structure
**Best Practices:** **Best Practices:**
- Demonstrate current industry best practices - Demonstrate current industry best practices
- Avoid deprecated or outdated approaches - Avoid deprecated or outdated approaches
- Show security-conscious coding - Show security-conscious coding
@ -162,21 +160,25 @@ Develop all code examples referenced in the chapter:
Create 4-6 end-of-chapter exercises with progressive difficulty: Create 4-6 end-of-chapter exercises with progressive difficulty:
**Basic Exercises (2-3):** **Basic Exercises (2-3):**
- Direct application of chapter concepts - Direct application of chapter concepts
- Provide clear guidance and hints - Provide clear guidance and hints
- Solutions or detailed hints included - Solutions or detailed hints included
**Intermediate Exercises (1-2):** **Intermediate Exercises (1-2):**
- Require combining multiple concepts - Require combining multiple concepts
- More independence required - More independence required
- Hints provided, full solutions optional - Hints provided, full solutions optional
**Challenge Exercise (1):** **Challenge Exercise (1):**
- Advanced application requiring creativity - Advanced application requiring creativity
- Minimal guidance - Minimal guidance
- Extension of chapter topics - Extension of chapter topics
**For Each Exercise:** **For Each Exercise:**
- Clear problem statement - Clear problem statement
- Specific requirements - Specific requirements
- Estimated completion time - Estimated completion time
@ -193,21 +195,25 @@ Create 4-6 end-of-chapter exercises with progressive difficulty:
Conclude with effective summary (1-2 pages): Conclude with effective summary (1-2 pages):
**Key Takeaways:** **Key Takeaways:**
- Bullet list of main concepts covered - Bullet list of main concepts covered
- Important terms and definitions - Important terms and definitions
- Core skills acquired - Core skills acquired
**What You Accomplished:** **What You Accomplished:**
- Concrete deliverables from this chapter - Concrete deliverables from this chapter
- Skills checklist readers can verify - Skills checklist readers can verify
- How this builds on previous learning - How this builds on previous learning
**Looking Ahead:** **Looking Ahead:**
- Preview of next chapter - Preview of next chapter
- How upcoming content will build on this foundation - How upcoming content will build on this foundation
- Why the next topic matters - Why the next topic matters
**Further Reading (Optional):** **Further Reading (Optional):**
- Official documentation links - Official documentation links
- Recommended articles or resources - Recommended articles or resources
- Community resources - Community resources
@ -220,17 +226,20 @@ Conclude with effective summary (1-2 pages):
Link to related content throughout the chapter: Link to related content throughout the chapter:
**Internal References:** **Internal References:**
- "See Chapter 2, Section 2.3 for database setup" - "See Chapter 2, Section 2.3 for database setup"
- "We'll explore advanced patterns in Chapter 8" - "We'll explore advanced patterns in Chapter 8"
- "Review the glossary in Appendix A for term definitions" - "Review the glossary in Appendix A for term definitions"
**External References:** **External References:**
- Official documentation (with URLs) - Official documentation (with URLs)
- Standards or specifications (RFCs, PEPs, etc.) - Standards or specifications (RFCs, PEPs, etc.)
- Relevant research papers or articles - Relevant research papers or articles
- Community resources (forums, guides) - Community resources (forums, guides)
**Best Practices:** **Best Practices:**
- Be specific with chapter and section numbers - Be specific with chapter and section numbers
- Test all URLs for validity - Test all URLs for validity
- Prefer stable, official sources - Prefer stable, official sources
@ -241,18 +250,21 @@ Link to related content throughout the chapter:
Provide curated resources for deeper learning: Provide curated resources for deeper learning:
**Official Sources:** **Official Sources:**
- Language documentation - Language documentation
- Framework guides - Framework guides
- API references - API references
- Release notes for features used - Release notes for features used
**Community Resources:** **Community Resources:**
- Well-regarded tutorials - Well-regarded tutorials
- Video explanations - Video explanations
- Community forums or discussion - Community forums or discussion
- GitHub repositories - GitHub repositories
**Quality Over Quantity:** **Quality Over Quantity:**
- 5-8 truly helpful resources beats 20 mediocre ones - 5-8 truly helpful resources beats 20 mediocre ones
- Annotate each resource with what it provides - Annotate each resource with what it provides
- Organize by topic or learning path - Organize by topic or learning path
@ -262,12 +274,14 @@ Provide curated resources for deeper learning:
Ensure all promised learning outcomes are covered: Ensure all promised learning outcomes are covered:
**For Each Learning Objective:** **For Each Learning Objective:**
- Where in the chapter is this taught? - Where in the chapter is this taught?
- Are there examples demonstrating this skill? - Are there examples demonstrating this skill?
- Can readers practice this skill in exercises? - Can readers practice this skill in exercises?
- Is there clear evidence of skill achievement? - Is there clear evidence of skill achievement?
**Self-Check:** **Self-Check:**
- Read each objective - Read each objective
- Find the section(s) teaching it - Find the section(s) teaching it
- Verify hands-on practice exists - Verify hands-on practice exists
@ -282,6 +296,7 @@ Final quality check before review:
**Run:** execute-checklist.md with chapter-completeness-checklist.md **Run:** execute-checklist.md with chapter-completeness-checklist.md
**Checklist Includes:** **Checklist Includes:**
- All sections from outline present - All sections from outline present
- Learning objectives fully addressed - Learning objectives fully addressed
- Code examples tested and working - Code examples tested and working

328
expansion-packs/bmad-technical-writing/tasks/write-introduction.md Normal file
View File

@ -0,0 +1,328 @@
<!-- Powered by BMAD™ Core -->
# Write Chapter Introduction
---
task:
id: write-introduction
name: Write Chapter Introduction
description: Create engaging chapter introduction with learning objectives, prerequisites, and roadmap
persona_default: tutorial-architect
inputs: - chapter-number and title - chapter-outline (topics to be covered) - learning-objectives
steps: - Create compelling hook or opening - State chapter overview and scope - List learning objectives clearly - Define prerequisites explicitly - Explain what readers will build or learn - Provide time estimate for chapter - Create section roadmap - Connect to previous and next chapters - Review for engagement and clarity - Validate prerequisites are accurate - Use template introduction-tmpl.yaml with create-doc.md task (if needed)
output: Chapter introduction section (first 1-3 pages)
---
## Purpose
This task guides you through creating an effective chapter introduction that hooks readers, sets clear expectations, and provides a roadmap for learning. The result is an introduction that motivates readers and prepares them for success.
## Prerequisites
Before starting this task:
- Have chapter outline completed
- Know learning objectives for this chapter
- Understand what previous chapters covered
- Access to book-structures.md knowledge base
## Workflow Steps
### 1. Create Compelling Hook
Start with an engaging opening (1-2 paragraphs):
**Hook types:**
**Problem-based:** Start with a common problem readers face
```
Have you ever deployed an application only to have it mysteriously fail in production despite working perfectly on your laptop? This frustrating experience is exactly what containerization solves. In this chapter, you'll learn how Docker ensures your code runs consistently everywhere.
```
**Story-based:** Begin with a real-world scenario
```
In 2013, a single misconfigured load balancer brought down Netflix for three hours, costing millions in lost revenue. Modern resilient architectures prevent these single points of failure. This chapter teaches you to build systems that stay running even when components fail.
```
**Question-based:** Pose thought-provoking questions
```
What happens when your database receives 100,000 requests per second? How do you scale beyond a single server? In this chapter, you'll discover horizontal scaling patterns that power the world's largest applications.
```
**Outcome-based:** Show what readers will achieve
```
By the end of this chapter, you'll have built a fully automated CI/CD pipeline that tests, builds, and deploys your application with a single git push. No more manual deployments or forgotten steps.
```
**Selection criteria:**
- Relevant to reader's experience
- Immediately shows value
- Creates curiosity or urgency
- Specific, not generic
### 2. State Chapter Overview
Provide 2-3 sentences summarizing the chapter:
**Include:**
- Main topic or theme
- Scope (what's covered, what's not)
- Approach (hands-on, conceptual, project-based)
- Key takeaway
**Example:**
"This chapter covers Docker containerization from development through production deployment. You'll build a multi-container application with a Python backend, Redis cache, and PostgreSQL database. By the end, you'll understand how containers solve the 'it works on my machine' problem and enable consistent deployment across environments."
**Avoid:**
- Vague statements ("We'll learn about Docker")
- Listing every tiny detail
- Assuming too much prior knowledge
### 3. List Learning Objectives
Present 3-5 specific, measurable learning objectives:
**Format:**
"By the end of this chapter, you will be able to:"
1. Create Dockerfiles to containerize Python applications
2. Configure multi-container applications using Docker Compose
3. Debug containers using logs and interactive shells
4. Deploy containerized applications to production environments
5. Implement health checks and container restart policies
**Guidelines:**
- Use action verbs (create, implement, debug, analyze)
- Make them measurable and observable
- Progress from simple to complex
- Align with Bloom's Taxonomy level for this chapter
- Match what's actually covered (no surprise objectives)
**Good vs. Bad:**
- ✅ "Build a Docker Compose configuration with 3 services"
- ❌ "Understand Docker" (too vague, not measurable)
- ✅ "Debug container networking issues using docker network commands"
- ❌ "Know how to fix problems" (not specific enough)
### 4. Define Prerequisites
Explicitly state what readers need before starting:
**Categories:**
**Previous chapters:**
"You should have completed Chapters 1-3, which covered Python basics, virtual environments, and web framework fundamentals."
**External knowledge:**
"This chapter assumes you're comfortable with:"
- Command line basics (cd, ls, running commands)
- Git version control (clone, commit, push)
- Basic Python syntax and functions
**Software/tools:**
"Before starting, ensure you have:"
- Docker Desktop installed (version 20.10+)
- Python 3.11 or higher
- A text editor or IDE
- 4GB free disk space
**Skills:**
"Required skills:"
- Can run commands in a terminal
- Comfortable reading stack traces
- Basic understanding of client-server architecture
**Estimated time:**
"This chapter takes approximately 3-4 hours to complete, including hands-on exercises."
**Why explicit prerequisites matter:**
- Prevents frustration from missing knowledge
- Lets readers assess readiness
- Identifies gaps to fill first
- Sets realistic time expectations
### 5. Explain What Readers Will Build
Describe the hands-on project or outcome:
**Project-based chapter:**
"You'll build a complete task management API with the following features:
- RESTful endpoints for creating, reading, updating, and deleting tasks
- JWT authentication to secure endpoints
- PostgreSQL database for persistence
- Redis caching to improve performance
- Docker Compose configuration for one-command deployment
The finished project will demonstrate production-ready API design patterns you can apply to your own applications."
**Concept-based chapter:**
"This chapter equips you with the mental models to reason about distributed systems. Through diagrams and examples, you'll learn to identify consistency problems, choose appropriate replication strategies, and understand CAP theorem trade-offs. While we won't build a distributed database, you'll gain the knowledge to use existing distributed systems effectively."
**Include:**
- Tangible deliverable or understanding
- How it relates to real-world use
- What makes it interesting or valuable
- Screenshot or diagram of end result (if applicable)
### 6. Provide Time Estimate
Set realistic expectations:
**Format:**
"⏱️ Estimated time: 3-4 hours
- Reading and examples: 1-2 hours
- Hands-on exercises: 1.5-2 hours
- Additional exploration: 30 minutes"
**Consider:**
- Target audience's speed
- Complexity of exercises
- Debugging time for common issues
- Optional deep-dive sections
### 7. Create Section Roadmap
Outline the chapter structure:
**Format:**
"Here's what we'll cover:
**Section 1: Container Fundamentals** (pages X-Y)
You'll learn what containers are, how they differ from virtual machines, and why they're valuable for development and deployment.
**Section 2: Creating Dockerfiles** (pages X-Y)
We'll write Dockerfiles to containerize a Python application, exploring multi-stage builds and optimization techniques.
**Section 3: Multi-Container Applications** (pages X-Y)
You'll orchestrate multiple containers using Docker Compose, connecting a web app, database, and cache.
**Section 4: Production Deployment** (pages X-Y)
Finally, we'll deploy to production, implementing health checks, logging, and restart policies.
**Hands-on Exercise** (pages X-Y)
Build a complete containerized application from scratch and deploy it.
**Summary and Next Steps** (page X)
We'll recap key concepts and preview Chapter 8's coverage of Kubernetes orchestration."
**Include for each section:**
- Section number and title
- Brief description (1 sentence)
- Page range (if known)
- What readers will do (read, build, practice)
### 8. Connect to Previous and Next Chapters
Show the learning progression:
**Previous chapters:**
"In Chapter 5, you deployed applications directly to servers, manually installing dependencies and configuring services. You experienced the fragility of environment-specific issues and configuration drift. This chapter solves those problems with containerization."
**Current chapter:**
"Here, you'll package applications into portable containers that run identically everywhere."
**Next chapters:**
"In Chapter 8, you'll orchestrate these containers at scale using Kubernetes, managing hundreds of containers across multiple servers. Chapter 9 builds on this foundation with service mesh patterns for microservices communication."
**Purpose:**
- Shows coherent learning arc
- Motivates why this chapter matters
- Previews what's coming
- Reinforces previous learning
### 9. Review for Engagement
Validate the introduction:
- [ ] Does the hook grab attention immediately?
- [ ] Are learning objectives specific and measurable?
- [ ] Are prerequisites explicit and complete?
- [ ] Is the project/outcome clear and compelling?
- [ ] Does the roadmap provide clear structure?
- [ ] Is the tone encouraging and accessible?
- [ ] Does it avoid jargon or define terms?
- [ ] Is the time estimate realistic?
**Tone check:**
- ✅ "You'll build a RESTful API that handles authentication"
- ❌ "We will be discussing API concepts" (passive, boring)
- ✅ "This pattern prevents race conditions in concurrent systems"
- ❌ "Obviously, you wouldn't want race conditions" (condescending)
### 10. Validate Prerequisites
Cross-check prerequisites against chapter content:
- [ ] Do we use concepts from listed previous chapters?
- [ ] Are required tools actually needed for exercises?
- [ ] Is assumed knowledge actually assumed?
- [ ] Are there any surprise prerequisites?
- [ ] Is the time estimate reasonable?
## Success Criteria
A completed chapter introduction should have:
- [ ] Compelling hook (1-2 paragraphs)
- [ ] Clear chapter overview (2-3 sentences)
- [ ] 3-5 specific learning objectives with action verbs
- [ ] Explicit prerequisites (chapters, knowledge, tools, skills)
- [ ] Description of what readers will build/learn
- [ ] Realistic time estimate
- [ ] Section roadmap with brief descriptions
- [ ] Connection to previous and next chapters
- [ ] Encouraging, accessible tone
- [ ] Length: 1-3 pages maximum
## Common Pitfalls to Avoid
- **Boring opening**: Generic statements like "This chapter covers Docker"
- **Vague objectives**: "Understand containers" instead of "Build a Dockerfile"
- **Hidden prerequisites**: Assuming knowledge without stating it
- **Too long**: Introductions shouldn't exceed 3 pages
- **No roadmap**: Readers need to see the structure
- **Disconnected**: Doesn't connect to previous learning
- **Overpromising**: Objectives not actually met in chapter
- **Intimidating**: Makes chapter sound harder than it is
## Notes and Warnings
- **Hook is critical**: First paragraph determines if readers engage
- **Prerequisites prevent frustration**: Better to over-explain than assume
- **Roadmap provides confidence**: Readers want to see the path
- **Objectives = contract**: You must deliver on stated objectives
- **Time estimates**: Be realistic, not optimistic
- **Tone matters**: Encouraging, not condescending or overly casual
## Next Steps
After writing introduction:
1. Write main chapter sections following roadmap
2. Ensure content matches stated learning objectives
3. Create exercises that validate objectives
4. Write chapter summary that recaps objectives
5. Verify prerequisites were actually prerequisites
6. Update introduction if chapter content changes

365
expansion-packs/bmad-technical-writing/tasks/write-summary.md Normal file
View File

@ -0,0 +1,365 @@
<!-- Powered by BMAD™ Core -->
# Write Chapter Summary
---
task:
id: write-summary
name: Write Chapter Summary
description: Create concise chapter summary recapping key concepts and previewing next steps
persona_default: tutorial-architect
inputs: - completed chapter content - learning-objectives (from introduction) - next-chapter topic
steps: - Review chapter content thoroughly - Identify key concepts covered (3-5 main points) - Summarize main learning points in bullet format - Recap what readers accomplished - Reinforce learning objectives were met - Preview next chapter topic - Suggest further reading or practice - Keep concise (1-2 pages maximum) - Review for completeness - Ensure alignment with introduction
output: Chapter summary section (final 1-2 pages)
---
## Purpose
This task guides you through creating an effective chapter summary that reinforces learning, validates progress, and motivates continued reading. The result is a concise recap that helps readers consolidate knowledge.
## Prerequisites
Before starting this task:
- Have complete chapter content
- Know learning objectives from introduction
- Understand next chapter's topic
- Access to book-structures.md knowledge base
## Workflow Steps
### 1. Review Chapter Content
Re-read the chapter with summary in mind:
**Identify:**
- Key concepts introduced
- Main skills practiced
- Important patterns or principles
- Common pitfalls covered
- Hands-on projects completed
**Questions to ask:**
- What are the 3-5 most important takeaways?
- What would readers need to remember in 6 months?
- What enables them to build their own projects?
- What concepts appear in later chapters?
### 2. Identify Key Concepts
List 3-5 main concepts (no more than 5):
**Selection criteria:**
- Essential to understanding this topic
- Referenced in later chapters
- Applicable to real-world projects
- Aligned with learning objectives
- Not trivial details
**Example:**
From a chapter on Docker:
1. Container isolation enables consistent environments
2. Dockerfiles define reproducible image builds
3. Multi-stage builds optimize image size
4. Docker Compose orchestrates multi-container apps
5. Health checks enable automatic container restart
**Avoid:**
- Too many points (overwhelming)
- Trivial details ("We installed Docker")
- Concepts not actually covered
- Vague statements ("Containers are useful")
### 3. Summarize Main Learning Points
Create a bullet list of key takeaways:
**Format:**
"## Summary
In this chapter, you learned:
- **Container fundamentals**: Containers provide lightweight, isolated environments that bundle applications with their dependencies, ensuring consistent behavior across development, testing, and production.
- **Dockerfile best practices**: Multi-stage builds, layer caching, and minimal base images reduce image size and build time. The order of COPY and RUN commands matters for cache efficiency.
- **Docker Compose orchestration**: YAML configuration files define multi-container applications, networks, and volumes, enabling one-command deployment of complex systems.
- **Production deployment patterns**: Health checks, restart policies, and proper logging ensure containerized applications run reliably in production.
- **Debugging techniques**: Interactive shells (docker exec), logs (docker logs), and network inspection (docker network) help diagnose container issues."
**Guidelines:**
- One concept per bullet
- 1-2 sentences each
- Bold the concept name
- Include the "why" or "so what"
- Use concrete language, not abstract
- Match terminology from chapter
**Good vs. Bad:**
- ✅ "Health checks detect and restart failed containers automatically"
- ❌ "Health checks are important" (why? how?)
- ✅ "Multi-stage builds separate build tools from runtime images, reducing final image size by 70%"
- ❌ "You can optimize Docker images" (how? what's the benefit?)
### 4. Recap What Readers Accomplished
Highlight concrete achievements:
**Format:**
"You built several practical projects in this chapter:
- **Containerized Python API**: You created a Dockerfile for a Flask application, including dependencies, environment configuration, and entry point.
- **Multi-container application**: Your Docker Compose configuration connected a web app, PostgreSQL database, and Redis cache with defined networks and persistent volumes.
- **Production deployment**: You deployed containers with health checks, restart policies, and centralized logging.
You can now containerize your own applications and deploy them consistently across any Docker-enabled environment."
**Include:**
- Specific projects or exercises completed
- Skills demonstrated
- How these apply beyond the chapter
- What readers can build independently now
**Tone:**
- Celebratory ("You built...")
- Specific ("containerized Python API" not "learned Docker")
- Empowering ("You can now...")
### 5. Reinforce Learning Objectives Were Met
Explicitly connect back to stated objectives:
**Format:**
"Returning to our learning objectives from the beginning of the chapter:
✅ **Create Dockerfiles to containerize Python applications** – You wrote Dockerfiles with multi-stage builds and optimized layer caching.
✅ **Configure multi-container applications using Docker Compose** – Your docker-compose.yml defined services, networks, and volumes for a complete application stack.
✅ **Debug containers using logs and interactive shells** – You used docker logs, docker exec, and docker network inspect to diagnose issues.
✅ **Deploy containerized applications to production** – You configured health checks, restart policies, and persistent storage for production deployment.
✅ **Implement health checks and restart policies** – Your production containers automatically restart on failure and report health status."
**Guidelines:**
- Use checkmarks (✅) to show completion
- Repeat objectives verbatim from introduction
- Add brief evidence of achievement
- If any objective wasn't fully met, acknowledge it
- Reinforce that stated goals were achieved
**Why this matters:**
- Validates reader's progress
- Builds confidence
- Shows chapter delivered on promises
- Provides sense of accomplishment
### 6. Preview Next Chapter
Connect to what's coming:
**Format:**
"## What's Next
Now that you can containerize and deploy applications with Docker, you're ready to scale beyond a single host.
**In Chapter 8: Kubernetes Orchestration**, you'll learn to:
- Manage hundreds of containers across multiple servers
- Implement automatic scaling based on load
- Achieve zero-downtime deployments with rolling updates
- Configure service discovery and load balancing
- Monitor cluster health and resource usage
You'll use your Docker expertise as the foundation, with Kubernetes adding orchestration, scaling, and resilience for production-grade deployments.
The containers you built in this chapter will run on Kubernetes with minimal changes, but you'll gain powerful new capabilities for managing them at scale."
**Include:**
- Next chapter number and title
- How it builds on this chapter
- Preview of key topics (3-5 bullet points)
- Why readers should be excited
- Connection between chapters
**Avoid:**
- Detailed explanations (save for next chapter)
- Spoiling surprises or major reveals
- Making next chapter sound harder than it is
- Disconnected topics
### 7. Suggest Further Reading and Practice
Provide optional resources:
**Format:**
"## Further Reading and Practice
**Recommended practice:**
- Containerize one of your own applications using the patterns from this chapter
- Experiment with different base images (alpine, slim, distroless) and compare sizes
- Add health checks to an existing application and test failure scenarios
- Set up Docker Compose for a multi-tier application you're familiar with
**Additional resources:**
- Docker official documentation: https://docs.docker.com/
- Docker best practices guide: https://docs.docker.com/develop/dev-best-practices/
- "The 12-Factor App" methodology: https://12factor.net/
- Docker Hub official images: https://hub.docker.com/_/python
**Community:**
- Docker community forums: https://forums.docker.com/
- r/docker subreddit for questions and examples
- Docker Compose examples repository: https://github.com/docker/awesome-compose"
**Include:**
- Practice exercises (apply to own projects)
- Official documentation
- Related articles or books
- Community resources
- Code repositories or examples
**Guidelines:**
- Keep it optional (not required)
- Prioritize quality over quantity (3-5 resources max)
- Include brief description of each
- Indicate difficulty level if relevant
- Prefer official/authoritative sources
### 8. Keep It Concise
Summaries should be brief:
**Length guidelines:**
- 1-2 pages maximum
- 300-500 words typical
- If longer, you're re-teaching, not summarizing
**Structure:**
1. Summary (key concepts) - 1/2 page
2. What you accomplished - 1/4 page
3. Learning objectives recap - 1/4 page
4. What's next - 1/4 page
5. Further reading (optional) - 1/4 page
**Avoid:**
- Repeating chapter content verbatim
- Introducing new concepts
- Detailed explanations
- Code examples (reference them, don't repeat)
### 9. Review for Completeness
Validate the summary:
- [ ] Are key concepts identified (3-5)?
- [ ] Are learning points clearly summarized?
- [ ] Are accomplishments celebrated?
- [ ] Are stated objectives validated?
- [ ] Is next chapter previewed?
- [ ] Are further resources provided?
- [ ] Is it concise (1-2 pages)?
- [ ] Does it match introduction tone?
**Alignment check:**
- Introduction stated objectives → Summary validates them
- Introduction promised content → Summary confirms delivery
- Introduction set expectations → Summary meets them
### 10. Ensure Alignment with Introduction
Cross-reference introduction and summary:
**Introduction said:**
"By the end of this chapter, you will be able to create Dockerfiles to containerize Python applications."
**Summary must confirm:**
"✅ Create Dockerfiles to containerize Python applications – You wrote Dockerfiles with multi-stage builds and optimized layer caching."
**Check:**
- [ ] Every objective has a checkmark in summary
- [ ] Projects mentioned in introduction were completed
- [ ] Tone and voice are consistent
- [ ] Prerequisites mentioned were actually prerequisites
- [ ] Time estimate was reasonable (note if not)
## Success Criteria
A completed chapter summary should have:
- [ ] 3-5 key concepts clearly summarized
- [ ] Bullet list of main learning points
- [ ] Recap of reader accomplishments
- [ ] Validation of all stated learning objectives
- [ ] Preview of next chapter with connection
- [ ] Optional further reading suggestions
- [ ] Concise length (1-2 pages maximum)
- [ ] Consistent tone with introduction
- [ ] No new concepts introduced
- [ ] Celebratory and empowering tone
## Common Pitfalls to Avoid
- **Too long**: Summaries shouldn't exceed 2 pages
- **Too detailed**: Don't re-teach, just recap
- **Vague**: "You learned about Docker" instead of specific accomplishments
- **Missing objectives**: Every stated objective needs validation
- **Disconnected**: Next chapter preview seems unrelated
- **No celebration**: Acknowledge reader's hard work
- **New content**: Summary introduces concepts not in chapter
- **Boring**: Just listing topics instead of emphasizing achievements
## Notes and Warnings
- **Summaries aid retention**: Well-written summaries improve learning outcomes
- **Validation matters**: Readers need confirmation they achieved objectives
- **Preview motivates**: Good preview encourages continued reading
- **Be specific**: "You built X" is better than "We covered X"
- **Match introduction**: Summary and introduction should bookend the chapter
- **Celebrate progress**: Readers accomplished something, acknowledge it
## Next Steps
After writing summary:
1. Ensure introduction and summary form coherent bookends
2. Verify all learning objectives were actually met
3. Update introduction if chapter deviated from plan
4. Add summary to chapter outline/structure
5. Review entire chapter for coherent flow
6. Begin planning next chapter based on preview

125
expansion-packs/bmad-technical-writing/templates/api-reference-tmpl.yaml Normal file
View File

@ -0,0 +1,125 @@
# <!-- Powered by BMAD™ Core -->
---
template:
id: api-reference
name: API Reference Documentation
version: 1.0
description: Comprehensive API/function reference documentation with parameters, return values, and examples
output:
format: markdown
filename: "{{api_name}}-reference.md"
workflow:
elicitation: true
allow_skip: false
sections:
- id: overview
title: API Overview
instruction: |
Provide high-level API information:
- Module, class, or function name
- Full signature (function signature, class definition, etc.)
- Import path or package location
- Version introduced (if applicable)
- Deprecation status (if applicable)
elicit: true
- id: purpose
title: Purpose and Description
instruction: |
Explain what this API does:
- Primary purpose in 1-2 sentences
- Use cases where this API is appropriate
- When NOT to use this API
- Related APIs that might be alternatives
elicit: true
- id: parameters
title: Parameters
instruction: |
Document all parameters in a table format:
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| name | string | Yes | - | The user's full name |
| age | int | No | 0 | User's age in years |
For each parameter:
- Name exactly as it appears in code
- Type (string, int, bool, object, array, etc.)
- Required or Optional
- Default value if optional
- Clear description of what it does
- Valid ranges or constraints (if applicable)
- Examples of valid values
- id: return_value
title: Return Value
instruction: |
Document what the API returns:
- Return type (including null/None if possible)
- Description of the returned value
- Structure of return object (if complex)
- Return value examples
- Conditions affecting return value
- id: exceptions
title: Exceptions and Errors
instruction: |
List possible errors and exceptions:
| Exception/Error | Condition | How to Handle |
|----------------|-----------|---------------|
| ValueError | Invalid input format | Validate input before calling |
| FileNotFoundError | File path doesn't exist | Check file exists first |
For each exception:
- Exception name or error code
- What triggers this exception
- How to prevent or handle it
- id: usage_examples
title: Usage Examples
instruction: |
Provide 2-3 realistic code examples:
**Example 1: Basic usage**
```python
# Show the simplest, most common use case
result = api_function(required_param="value")
print(result)
```
**Example 2: Advanced usage**
```python
# Show more complex scenario with optional parameters
result = api_function(
required_param="value",
optional_param=42,
flags={"debug": True}
)
```
**Example 3: Error handling**
```python
# Show proper error handling
try:
result = api_function(param="value")
except ValueError as e:
print(f"Invalid input: {e}")
```
elicit: true
- id: notes
title: Notes and Warnings
instruction: |
Include important considerations:
- Performance implications
- Thread safety
- Platform-specific behavior
- Common pitfalls
- Best practices
- Security considerations
- id: related
title: Related Functions and References
instruction: |
Link to related APIs:
- Similar functions that work together
- Alternative approaches
- Required setup functions
- Functions that use this API's output
- Relevant documentation sections

106
expansion-packs/bmad-technical-writing/templates/appendix-tmpl.yaml Normal file
View File

@ -0,0 +1,106 @@
# <!-- Powered by BMAD™ Core -->
---
template:
id: appendix
name: Appendix
version: 1.0
description: Reference appendix with supplementary material, installation guides, and troubleshooting
output:
format: markdown
filename: "appendix-{{appendix_id}}.md"
workflow:
elicitation: true
allow_skip: false
sections:
- id: title_purpose
title: Appendix Title and Purpose
instruction: |
Define this appendix:
- Appendix letter/number (Appendix A, B, etc.)
- Clear, descriptive title
- What supplementary information it contains
- Why this content is in an appendix vs. main chapters
- Who should reference this appendix
elicit: true
- id: reference_material
title: Reference Material
instruction: |
Include reference tables, charts, or specifications:
- API reference tables
- Configuration options
- Error code listings
- Compatibility matrices
- Command-line flag references
- Keyboard shortcuts
- Regular expression patterns
- Data format specifications
Structure as tables or lists for easy scanning.
- id: installation
title: Installation and Setup Guides
instruction: |
Platform-specific installation instructions:
**For each platform (Windows, macOS, Linux):**
- Prerequisites check (OS version, dependencies)
- Step-by-step installation commands
- Verification steps
- Common installation issues
- Environment configuration
**Include:**
- Package manager commands (apt, brew, choco)
- Version constraints
- Path configuration
- IDE setup (if applicable)
- id: troubleshooting
title: Troubleshooting Common Issues
instruction: |
Document frequent problems and solutions:
**For each issue:**
- Symptom/error message
- Root cause explanation
- Step-by-step solution
- Prevention tips
- Related issues
Organize by category:
- Installation problems
- Environment/configuration issues
- Runtime errors
- Platform-specific problems
- Version compatibility issues
- id: additional_resources
title: Additional Resources and Links
instruction: |
Curated resource list:
**Official Documentation:**
- Language/framework docs
- API references
- Release notes
**Tools:**
- IDEs and editors
- Testing frameworks
- Deployment tools
- Debugging utilities
**Learning Resources:**
- Related books
- Online courses
- Video tutorials
- Blog posts and articles
**Community:**
- Forums and Stack Overflow tags
- Discord/Slack channels
- Mailing lists
- Conferences and meetups
For each resource:
- Name and URL
- Brief description
- Why it's useful

123
expansion-packs/bmad-technical-writing/templates/diagram-spec-tmpl.yaml Normal file
View File

@ -0,0 +1,123 @@
# <!-- Powered by BMAD™ Core -->
---
template:
id: diagram-spec
name: Diagram Specification
version: 1.0
description: Technical diagram design specification for visual documentation
output:
format: markdown
filename: "{{diagram_id}}-spec.md"
workflow:
elicitation: true
allow_skip: false
sections:
- id: purpose
title: Diagram Purpose and Context
instruction: |
Define why this diagram is needed:
- Chapter and section where diagram appears
- Concept or process being visualized
- Learning objective this diagram supports
- What text explanation it accompanies
- Audience skill level
elicit: true
- id: diagram_type
title: Diagram Type
instruction: |
Select the appropriate diagram type:
**Process/Flow Diagrams:**
- Flowchart: Decision trees, algorithms, processes
- Sequence diagram: Interactions over time, API calls
- Activity diagram: Workflows, user journeys
- Data flow diagram: Data movement through systems
**Structure Diagrams:**
- Architecture diagram: System components and relationships
- Class diagram: Object-oriented design
- Entity-relationship diagram: Database schemas
- Component diagram: Software architecture
**Other:**
- State diagram: State machines, lifecycle
- Network diagram: Infrastructure, deployment
- Timeline: Historical progression, versioning
- Comparison chart: Feature matrices, trade-offs
Specify the type and why it's appropriate for this content.
elicit: true
- id: elements
title: Key Elements and Components
instruction: |
List all elements that must appear in the diagram:
- Actors/entities (users, systems, services)
- Processes/functions (operations, transformations)
- Data stores (databases, caches, files)
- Decision points (conditionals, branches)
- Start/end points
- External systems or boundaries
For each element:
- Name/label text
- Shape or symbol to use
- Color or styling (if significant)
- id: relationships
title: Relationships and Flows
instruction: |
Define how elements connect:
- Arrows showing data/control flow
- Direction of relationships
- Sequence or order of operations
- Conditions or triggers
- Feedback loops
- Dependencies
Example: "User sends HTTP request → API Gateway → Authentication Service → Database"
elicit: true
- id: labels
title: Labels and Annotations
instruction: |
Specify all text labels needed:
- Edge labels (data types, protocols, methods)
- Callout boxes (important notes, explanations)
- Step numbers (for sequential processes)
- Legend entries (if symbols need explanation)
- Title and subtitle
Keep labels concise - detailed explanation belongs in body text.
- id: style
title: Style Requirements
instruction: |
Define visual styling:
- Color scheme (consistent with other book diagrams)
- Shape conventions (rectangles for processes, diamonds for decisions, etc.)
- Line styles (solid, dashed, dotted for different relationship types)
- Font size and style (must be legible when printed)
- Icon set or symbol library
- Background and borders
- id: size_format
title: Size and Format Requirements
instruction: |
Specify technical requirements:
- Dimensions (width x height in pixels or inches)
- Resolution (minimum DPI for print quality)
- File format (PNG, SVG, PDF)
- Orientation (portrait, landscape)
- Margin/padding requirements
- Page placement (full page, half page, inline)
- id: accessibility
title: Alternative Text Description
instruction: |
Write complete alt text for accessibility:
- Describe the diagram's purpose
- Explain the main flow or structure
- List key components
- Describe important relationships
- Provide equivalent information for screen readers
Alt text should enable someone who can't see the diagram to understand the concept.
Example: "Sequence diagram showing authentication flow: User submits credentials to web app, which forwards to auth service. Auth service validates against database and returns JWT token through web app to user."
elicit: true

73
expansion-packs/bmad-technical-writing/templates/learning-objectives-tmpl.yaml Normal file
View File

@ -0,0 +1,73 @@
# <!-- Powered by BMAD™ Core -->
---
template:
id: learning-objectives
name: Learning Objectives
version: 1.0
description: Define measurable learning objectives for chapters or sections using Bloom's Taxonomy
output:
format: markdown
filename: "{{chapter_id}}-learning-objectives.md"
workflow:
elicitation: true
allow_skip: false
sections:
- id: context
title: Context
instruction: |
Specify the context for these learning objectives:
- Chapter or section number and title
- Topic area being covered
- Position in overall book learning path
- Target audience skill level
elicit: true
- id: objectives
title: Learning Objectives
instruction: |
Define 3-5 measurable learning objectives using action verbs from Bloom's Taxonomy:
**Remember** (recall facts): define, list, identify, name, recognize
**Understand** (explain concepts): describe, explain, summarize, interpret
**Apply** (use knowledge): demonstrate, implement, execute, solve, build
**Analyze** (examine parts): compare, contrast, differentiate, debug, troubleshoot
**Evaluate** (make judgments): assess, critique, validate, defend, justify
**Create** (produce new): design, develop, architect, compose, construct
For each objective:
- Start with "By the end of this [chapter/section], you will be able to..."
- Use specific action verbs
- Make it measurable and observable
- Align with content covered
- Progress from lower to higher cognitive levels
Example: "By the end of this chapter, you will be able to design a RESTful API with proper authentication."
elicit: true
- id: prerequisites
title: Prerequisites
instruction: |
List what learners need to know before starting:
- Previous chapters that must be completed
- External knowledge assumed (programming languages, tools, concepts)
- Skills required (command line proficiency, Git basics, etc.)
- Environment setup needed
- id: success_criteria
title: Success Criteria
instruction: |
Define how learners can verify they've achieved the objectives:
- Observable behaviors or deliverables
- Self-assessment questions
- Practical demonstrations
- Code that should run successfully
- Problems they can now solve
Example: "You can successfully build and deploy a containerized web application."
- id: assessment
title: Assessment Approach
instruction: |
Describe how learning will be assessed:
- Practice exercises aligned with objectives
- Quiz questions covering key concepts
- Hands-on projects that demonstrate mastery
- Code challenges at appropriate difficulty
- Self-check opportunities throughout chapter

104
expansion-packs/bmad-technical-writing/templates/preface-tmpl.yaml Normal file
View File

@ -0,0 +1,104 @@
# <!-- Powered by BMAD™ Core -->
---
template:
id: preface
name: Book Preface
version: 1.0
description: Book preface/foreword structure introducing the book to readers
output:
format: markdown
filename: "preface.md"
workflow:
elicitation: true
allow_skip: false
sections:
- id: audience
title: Who This Book Is For
instruction: |
Define the target reader:
- Primary audience (role, skill level)
- Secondary audiences (related roles who may benefit)
- Specific skills or knowledge assumed
- Who this book is NOT for (helps set expectations)
Example: "This book is for intermediate Python developers who want to learn machine learning. You should be comfortable with Python syntax, functions, and object-oriented programming, but no ML experience is required."
elicit: true
- id: outcomes
title: What You'll Learn
instruction: |
High-level learning outcomes:
- 4-6 major skills or knowledge areas readers will gain
- Practical projects or deliverables they'll build
- How this knowledge advances their career or projects
- What makes this book's approach unique
Focus on transformation: "By the end of this book, you'll be able to..."
elicit: true
- id: prerequisites
title: Prerequisites
instruction: |
Explicitly state what readers need before starting:
- Programming languages and skill level
- Tools or software (IDEs, databases, cloud accounts)
- Concepts from other domains
- Hardware requirements (if applicable)
- Time commitment estimate
Be specific to prevent frustration: "Python 3.11+, Git basics, comfort with command line"
- id: organization
title: How This Book Is Organized
instruction: |
Explain the book's structure:
- Part/section breakdown (if applicable)
- Logical progression of topics
- Where beginners should start vs. experienced readers
- Chapters that can be skipped or read out of order
- How chapters build on each other
Example: "Part 1 covers fundamentals (Chapters 1-4), Part 2 applies these to real projects (Chapters 5-8), and Part 3 explores advanced topics (Chapters 9-12)."
elicit: true
- id: resources
title: Code Repository and Resources
instruction: |
Point readers to companion materials:
- GitHub repository URL
- Repository structure explanation
- How to download and use code examples
- Additional resources (datasets, APIs, tools)
- Errata and updates page
- Author website or contact info
- Community forum or Discord (if available)
- id: conventions
title: Conventions Used in This Book
instruction: |
Explain formatting and notation:
**Code formatting:**
- Inline code: `variable_name`
- Code blocks and how they're labeled
- Command-line vs. Python REPL examples
- Syntax highlighting conventions
**Callouts and notes:**
- 📝 Note: Additional information
- ⚠️ Warning: Important cautions
- 💡 Tip: Best practices and shortcuts
- 🔍 Deep Dive: Advanced details
**Special elements:**
- Exercises and how they're marked
- File paths and naming conventions
- Platform-specific instructions (Windows/Mac/Linux)
- id: acknowledgments
title: Acknowledgments
instruction: |
Thank those who contributed:
- Technical reviewers
- Publisher and editorial team
- Early readers or beta testers
- Open source projects used
- Family and supporters
- Community members
Keep it genuine and specific where possible.

199
expansion-packs/bmad-technical-writing/workflows/manning-meap-workflow.yaml Normal file
View File

@ -0,0 +1,199 @@
workflow:
id: manning-meap-workflow
name: Prepare Manning MEAP Chapter
description: Package individual chapter for Manning Early Access Program (MEAP). Ensures chapters work standalone, maintain consistent voice, link to code repository, and meet Manning's iterative publication requirements.
type: publisher-submission
version: 1.0
project_types:
- technical-book
publisher: Manning
sequence:
- agent: technical-editor
validates: chapter-standalone.md
requires: meap-chapter.md
notes: "MEAP chapters release individually, so each must work standalone. Verify: chapter introduces necessary context, doesn't assume previous chapters read, defines terms on first use, includes self-contained examples. Check manning-meap-checklist for standalone requirements. SAVE OUTPUT: standalone-validation-report.md"
- agent: technical-editor
validates: voice-consistency.md
requires: meap-chapter.md, previous-meap-chapters[]
notes: "Manning emphasizes consistent authorial voice across chapters. Verify: tone matches previous MEAP releases, terminology consistent, code style unchanged, explanation approach similar, reader engagement style consistent. Compare to published MEAP chapters. SAVE OUTPUT: voice-consistency-report.md"
- agent: book-publisher
creates: code-repository-links.md
requires: chapter-code/
notes: "Link chapter to GitHub code repository. Ensure: chapter code in dedicated folder, README.md explains setup, dependencies listed, running instructions clear, tests included. Add repository link to chapter introduction. Verify code works independently. SAVE OUTPUT: repository-integration-checklist.md"
- agent: book-publisher
validates: meap-format.md
requires: chapter-standalone-validated, voice-validated
notes: "Apply Manning MEAP format requirements. Check: chapter length (10-30 pages typical), code examples formatted, sidebars and margin notes used appropriately, figures captioned, exercises included. Run manning-meap-checklist. SAVE OUTPUT: meap-format-validation.md"
- agent: book-publisher
creates: meap-chapter-package/
requires: format-validated
notes: "Finalize MEAP chapter package for Manning. Structure: chapter-XX.md (or .docx), images/ (high-res), code-link.md, author-notes.md (changes from reader feedback if applicable). Prepare for incremental publication. SAVE OUTPUT: meap-package/chapter-{{chapter_number}}/"
flow_diagram: |
```mermaid
graph TD
A[Start: Chapter Draft Ready] --> B[technical-editor: Verify Standalone]
B --> C{Works Standalone?}
C -->|No| D[Add Context/Definitions]
D --> B
C -->|Yes| E[technical-editor: Check Voice Consistency]
E --> F{Voice Consistent?}
F -->|No| G[Adjust Tone/Style]
G --> E
F -->|Yes| H[book-publisher: Link Code Repository]
H --> I[book-publisher: Validate MEAP Format]
I --> J{Format Valid?}
J -->|No| K[Fix Format Issues]
K --> I
J -->|Yes| L[book-publisher: Finalize MEAP Package]
L --> M[Submit to Manning MEAP]
M --> N[Collect Reader Feedback]
N --> O{Revisions Needed?}
O -->|Yes| P[Revise Chapter]
P --> B
O -->|No| Q[Chapter Final for Print]
style Q fill:#90EE90
style B fill:#FFE4B5
style E fill:#FFE4B5
style I fill:#F0E68C
style L fill:#ADD8E6
style N fill:#FFD700
```
quality_gates:
standalone_requirements:
- Chapter introduces necessary background
- Doesn't assume previous chapters read
- Terms defined on first use (even if defined earlier)
- Examples self-contained
- Prerequisites explicitly stated
- Can be read out of sequence
- Checklist: manning-meap-checklist.md
voice_consistency:
- Tone matches previous MEAP chapters
- Terminology consistent across chapters
- Code style unchanged
- Explanation approach similar
- Reader engagement style consistent
- Formality level matches
code_integration:
- Code repository linked in chapter
- Chapter code in dedicated GitHub folder
- README.md with setup instructions
- Dependencies clearly listed
- Running instructions provided
- Tests included and passing
- Code works independently
meap_format:
- Chapter length appropriate (10-30 pages)
- Code examples properly formatted
- Sidebars for advanced topics
- Margin notes for additional context
- Figures with descriptive captions
- Exercises or practice problems included
- Summary section at end
handoff_prompts:
editor_standalone_check: "Standalone validation complete for Chapter {{chapter_number}}. {{issue_count}} context gaps identified. Chapter now includes necessary background, term definitions, and self-contained examples. Ready for voice consistency check."
editor_voice_check: "Voice consistency validated for Chapter {{chapter_number}}. Compared against {{previous_chapter_count}} previous MEAP chapters. Tone, terminology, and code style consistent. {{adjustment_count}} minor adjustments made. Ready for code integration."
publisher_code_link: "Code repository integration complete. Chapter {{chapter_number}} code available at {{repo_url}}/chapter-{{chapter_number}}. README.md includes setup and running instructions. {{test_count}} tests passing. Ready for MEAP format validation."
publisher_format_check: "MEAP format validation complete. Chapter {{chapter_number}} is {{page_count}} pages. {{code_example_count}} code examples, {{figure_count}} figures, {{exercise_count}} exercises included. All formatting requirements met. Ready for package finalization."
publisher_package: "MEAP chapter package finalized. Location: meap-package/chapter-{{chapter_number}}/. Includes: chapter file, {{image_count}} images, code repository link, author notes. Ready for Manning MEAP submission."
meap_published: "Chapter {{chapter_number}} published to Manning MEAP. Available to early access readers. Monitoring feedback at forum/discussion-{{chapter_number}}. Will incorporate feedback in final revision."
manning_meap_specific:
program_overview:
- MEAP = Manning Early Access Program
- Chapters released incrementally as written
- Readers purchase early access, get updates
- Reader feedback incorporated before print
- Iterative publication model
chapter_requirements:
- Must work standalone (readers may skip chapters)
- Consistent voice across all MEAP releases
- Code repository always up-to-date
- Length: 10-30 pages typical
- Quality: publishable, not draft quality
reader_feedback:
- Manning forum for reader discussions
- Authors expected to respond to feedback
- Incorporate substantive feedback in revisions
- Track feedback for each chapter
- Address technical errors immediately
iterative_improvements:
- MEAP chapters can be revised before print
- Reader feedback identifies confusing sections
- Errors caught early by engaged readers
- Opportunity to improve clarity
- Print version benefits from MEAP feedback
code_repository:
- GitHub repository required
- Public or private (Manning preference: public)
- Organized by chapter
- Keep synchronized with MEAP releases
- Update if reader feedback identifies bugs
time_estimates:
standalone_validation: "2-4 hours (add context as needed)"
voice_consistency_check: "1-2 hours"
code_repository_integration: "1-2 hours"
meap_format_validation: "1-2 hours"
package_preparation: "1 hour"
reader_feedback_review: "2-4 hours (ongoing after publication)"
revision_incorporation: "4-8 hours (if substantive feedback)"
total_initial_submission: "6-11 hours per chapter"
total_with_revisions: "10-19 hours per chapter"
best_practices:
- Make chapters standalone even if book has sequence
- Establish voice in first MEAP chapter, maintain it
- Link code repository early, keep it updated
- Respond to reader feedback promptly
- Use MEAP feedback to improve later chapters
- Sidebars for advanced topics (keeps main flow clean)
- "Manning's conversational style: you'll build, not we will"
- Margin notes add depth without interrupting flow
- Exercises reinforce learning
- Summary section helps retention
common_pitfalls:
- Assuming readers read previous MEAP chapters (they may not)
- Inconsistent voice between chapters (jarring for readers)
- Outdated code repository (frustrates readers)
- Ignoring reader feedback (missing improvement opportunities)
- Chapters too short (<10 pages, feels incomplete)
- Chapters too long (>40 pages, overwhelming for MEAP)
- Missing exercises (readers want practice)
- No summary section (no reinforcement)
- Undefined terms (assuming knowledge from earlier chapters)
- Broken code repository links (immediate reader complaint)
meap_feedback_workflow:
- Chapter published to MEAP
- Readers discuss in Manning forum
- Author monitors discussion weekly
- Categorize feedback: errors, unclear sections, requests
- Fix technical errors immediately (issue update)
- Plan clarity improvements for next revision
- Incorporate feedback before print deadline
- Thank engaged readers in acknowledgments
coordination_with_full_book:
- MEAP chapters become book chapters (with revisions)
- Maintain chapter numbering
- Standalone chapters fine; final book has continuity
- Cross-references added in final edit (after MEAP complete)
- Index added in final production (not in MEAP)
- MEAP readers get final book updates automatically

183
expansion-packs/bmad-technical-writing/workflows/oreilly-submission-workflow.yaml Normal file
View File

@ -0,0 +1,183 @@
workflow:
id: oreilly-submission-workflow
name: Prepare O'Reilly Submission
description: Package manuscript and code for O'Reilly submission. Ensures AsciiDoc or DocBook format requirements, Chicago Manual of Style adherence, Atlas platform compatibility, and code repository meet O'Reilly standards.
type: publisher-submission
version: 1.0
project_types:
- technical-book
publisher: O'Reilly
sequence:
- agent: technical-editor
validates: manuscript-format.md
requires: manuscript-chapters[]
notes: "Verify manuscript meets O'Reilly format requirements using oreilly-format-checklist. Check for AsciiDoc/DocBook structure if required, chapter organization, code tag conventions, admonitions (NOTE, TIP, WARNING, IMPORTANT, CAUTION), Chicago Manual of Style compliance. SAVE OUTPUT: format-validation-report.md"
- agent: book-publisher
creates: asciidoc-chapters/ (if needed)
requires: manuscript-markdown-chapters[]
notes: "If manuscript is in markdown, convert to AsciiDoc for O'Reilly Atlas platform. Ensure proper heading levels (=, ==, ===), code blocks with callouts, cross-references, index entries, admonition syntax. Validate conversion accuracy. SAVE OUTPUT: asciidoc-chapters/ (or note if already in AsciiDoc)"
- agent: technical-editor
validates: chicago-style.md
requires: manuscript-chapters[]
notes: "Apply Chicago Manual of Style guidelines (O'Reilly standard). Check: serial comma usage, number style (spell out one through nine), capitalization in headings, punctuation in lists, quotation marks vs. italics for terms, abbreviation consistency. SAVE OUTPUT: style-validation-report.md"
- agent: technical-editor
validates: code-tags.md
requires: manuscript-chapters[]
notes: "Verify all code blocks use proper O'Reilly tagging. Ensure: language identifiers correct, callouts numbered consistently, code annotations clear, syntax highlighting compatible, example titles descriptive. Check inline code uses proper markup. SAVE OUTPUT: code-tag-validation.md"
- agent: book-publisher
creates: oreilly-submission-package/
requires: format-validated, style-validated
notes: "Prepare submission package for O'Reilly Atlas or editorial team. Structure: /chapters/ (AsciiDoc or DocBook files), /images/ (vector formats preferred: SVG, PDF), /code/ (organized by chapter), book.asciidoc (master file), atlas.json (metadata), README.md. SAVE OUTPUT: submission-package/oreilly-submission/"
flow_diagram: |
```mermaid
graph TD
A[Start: Manuscript Ready] --> B[technical-editor: Verify Format]
B --> C{Format Valid?}
C -->|No| D[Fix Format Issues]
D --> B
C -->|Yes| E{AsciiDoc Required?}
E -->|Yes, Convert| F[book-publisher: Convert to AsciiDoc]
E -->|Already AsciiDoc| G[technical-editor: Apply Chicago Style]
F --> G
G --> H{Style Valid?}
H -->|No| I[Fix Style Issues]
I --> G
H -->|Yes| J[technical-editor: Verify Code Tags]
J --> K{Tags Valid?}
K -->|No| L[Fix Code Tags]
L --> J
K -->|Yes| M[book-publisher: Prepare Package]
M --> N[Submit to O'Reilly]
style N fill:#90EE90
style B fill:#FFE4B5
style F fill:#ADD8E6
style G fill:#FFE4B5
style J fill:#FFE4B5
style M fill:#F0E68C
```
quality_gates:
format_requirements:
- AsciiDoc or DocBook format (Atlas compatible)
- Proper heading hierarchy (=, ==, ===, ====)
- Admonitions use correct syntax (NOTE, TIP, WARNING, etc.)
- Cross-references formatted correctly
- Index entries marked
- Figure captions descriptive
- Checklist: oreilly-format-checklist.md
style_requirements:
- Chicago Manual of Style compliance
- Serial comma (Oxford comma) used consistently
- Numbers one-nine spelled out, 10+ as numerals
- Heading capitalization (sentence case)
- Quotation marks and italics used appropriately
- Consistent abbreviation style
- Checklist: chicago-style-checklist.md (if exists)
code_requirements:
- Language identifiers on all code blocks
- Callouts numbered consistently [1], [2], etc.
- Code annotations explain non-obvious lines
- Inline code uses backticks or proper markup
- Long lines handled appropriately
- Syntax highlighting compatible
handoff_prompts:
editor_format_check: "Format validation complete. {{chapter_count}} chapters checked. Format: {{format_type}}. {{issue_count}} formatting issues identified. Corrections needed before proceeding."
publisher_conversion: "{{chapter_count}} markdown chapters converted to AsciiDoc. Verified heading levels, code blocks, cross-references, and admonitions. Ready for Chicago style check."
editor_style_check: "Chicago Manual of Style validation complete. Reviewed {{chapter_count}} chapters. {{serial_comma_fixes}} serial comma fixes, {{number_style_fixes}} number style fixes, {{other_fixes}} other style corrections applied. Code tag validation in progress."
editor_code_tags: "Code tag validation complete. {{code_block_count}} code blocks verified. All have language identifiers and proper callouts. {{inline_code_count}} inline code elements checked. Ready for package preparation."
publisher_package: "O'Reilly submission package prepared. Structure: chapters/ ({{chapter_count}} AsciiDoc files), images/ ({{image_count}} SVG/PDF), code/ (tested examples), atlas.json (metadata). Package location: submission-package/oreilly-submission/"
ready_for_submission: "O'Reilly submission complete. All quality gates passed. Format: AsciiDoc, Style: Chicago Manual, Platform: Atlas-compatible. Ready for editorial review."
oreilly_specific_requirements:
file_formats:
- AsciiDoc preferred (Atlas platform)
- DocBook XML accepted
- Markdown convertible to AsciiDoc
- Master file: book.asciidoc
heading_style:
- Level 0: = Chapter Title
- Level 1: == Section
- Level 2: === Subsection
- Level 3: ==== Subsubsection
- Sentence case capitalization
admonitions:
- NOTE: Additional information
- TIP: Helpful suggestion
- WARNING: Potential problem
- "IMPORTANT: Critical information"
- "CAUTION: Proceed carefully"
- "Syntax: [NOTE] followed by ==== on new lines with content"
code_blocks:
- "Language identifier: [source,python]"
- "Callouts: <1>, <2> in code with explanations below"
- "Example title: .Filename or description"
- "Syntax: [[example-id]] for cross-reference"
images:
- Vector formats preferred: SVG, PDF
- Raster: PNG (300 DPI minimum)
- Filename: descriptive-name.svg
- Caption: .Figure caption text
- Alt text for accessibility
chicago_style_highlights:
- "Serial comma: apples, oranges, and bananas"
- "Numbers: one through nine, 10 and above"
- "Headings: Sentence case, not title case"
- "Quotes: double quotes for dialogue/direct quotes"
- "Italics: Book titles, emphasis, new terms on first use"
- "Abbreviations: Spell out on first use with acronym in parentheses"
time_estimates:
format_validation: "3-5 hours (depends on chapter count)"
asciidoc_conversion: "6-10 hours (if converting from markdown)"
chicago_style_check: "4-6 hours (manual review required)"
code_tag_verification: "2-4 hours"
package_preparation: "2-3 hours"
total_time_asciidoc_already: "11-18 hours"
total_time_conversion_needed: "17-28 hours"
best_practices:
- Learn AsciiDoc syntax early if starting in markdown
- Use O'Reilly's style guide and AsciiDoc guide
- Chicago Manual of Style is non-negotiable for O'Reilly
- Vector images (SVG) scale better than raster (PNG)
- Atlas platform has specific requirements - test early
- Code callouts should explain non-obvious lines
- Index entries improve discoverability
- Cross-references link related sections
- Consistent terminology throughout manuscript
- Test AsciiDoc rendering in Atlas preview
common_pitfalls:
- Using title case instead of sentence case in headings
- Missing serial commas (required by Chicago style)
- Inconsistent number style (mixing "5" and "five")
- Code blocks without language identifiers
- Raster images instead of vector (poor print quality)
- Incorrect admonition syntax (breaks Atlas rendering)
- Missing index entries (reduces book usability)
- Broken cross-references
- Hardcoded file paths in code examples
- Inconsistent abbreviation usage
atlas_platform_notes:
- O'Reilly uses Atlas for book production
- Atlas requires valid AsciiDoc or DocBook
- Preview your content in Atlas before final submission
- atlas.json contains book metadata (title, authors, ISBN)
- Images referenced must exist in images/ folder
- Code examples can link to GitHub repository
- Atlas generates multiple formats (PDF, EPUB, MOBI, HTML)

159
expansion-packs/bmad-technical-writing/workflows/packtpub-submission-workflow.yaml Normal file
View File

@ -0,0 +1,159 @@
workflow:
id: packtpub-submission-workflow
name: Prepare PacktPub Submission
description: Package manuscript and code for PacktPub submission. Ensures SharePoint format requirements, learning objectives, hands-on project structure, and code repository meet PacktPub standards.
type: publisher-submission
version: 1.0
project_types:
- technical-book
publisher: PacktPub
sequence:
- agent: technical-editor
validates: manuscript-format.md
requires: manuscript-chapters[]
notes: "Verify manuscript meets PacktPub SharePoint format requirements using packtpub-submission-checklist. Check chapter structure (What You'll Learn, Prerequisites, sections, Summary, Q&A), markdown formatting, code block style, callout boxes, screenshot captions. SAVE OUTPUT: format-validation-report.md"
- agent: code-curator
validates: code-repository
requires: chapter-code[]
notes: "Validate all code examples are tested and working. Ensure repository structure follows PacktPub standards: chapter folders, README per chapter, working code for all examples, tests passing, version compatibility verified. Run code-testing-checklist. SAVE OUTPUT: code-validation-report.md"
- agent: instructional-designer
creates: learning-objectives-summary.md
requires: manuscript-chapters[]
notes: "PacktPub emphasizes learning outcomes. Extract learning objectives from all chapters, create summary document showing progression, validate against learning-objectives-checklist. Ensure objectives use action verbs and are measurable. SAVE OUTPUT: docs/learning-objectives-summary.md"
- agent: book-publisher
creates: sharepoint-package/
requires: format-validation-passed, code-validation-passed
notes: "Prepare submission package for SharePoint upload. Structure: /ChapterFiles/ (Word .docx or markdown), /CodeFiles/ (organized by chapter), /ImageFiles/ (high-res screenshots), author-questionnaire.md, learning-objectives-summary.md. Verify all files named per PacktPub conventions. SAVE OUTPUT: submission-package/packtpub-submission/"
- agent: book-publisher
validates: final-submission.md
requires: sharepoint-package/
notes: "Final validation before submission. Run complete packtpub-submission-checklist. Verify: all chapters present, code tested, images high-res, learning objectives clear, Q&A sections included, author questionnaire complete. Create submission checklist document. SAVE OUTPUT: docs/packtpub-submission-checklist-final.md with status"
flow_diagram: |
```mermaid
graph TD
A[Start: Manuscript Ready] --> B[technical-editor: Verify Format]
B --> C{Format Valid?}
C -->|No| D[Fix Format Issues]
D --> B
C -->|Yes| E[code-curator: Validate Code]
E --> F{Code Tests Pass?}
F -->|No| G[Fix Code Issues]
G --> E
F -->|Yes| H[instructional-designer: Create Learning Objectives Summary]
H --> I[book-publisher: Prepare SharePoint Package]
I --> J[book-publisher: Final Validation]
J --> K{Ready?}
K -->|No| L[Address Issues]
L --> J
K -->|Yes| M[Submit to PacktPub]
style M fill:#90EE90
style B fill:#FFE4B5
style E fill:#FFE4B5
style I fill:#ADD8E6
style J fill:#F0E68C
```
quality_gates:
format_requirements:
- SharePoint-compatible format (Word .docx or markdown)
- Chapter structure includes What You'll Learn section
- Prerequisites clearly stated in each chapter
- Summary and Q&A sections present
- Code blocks properly formatted with language tags
- Callout boxes for notes, warnings, tips
- Screenshot captions descriptive
- Checklist: packtpub-submission-checklist.md
code_requirements:
- All code examples tested and working
- Repository structure: chapter-XX/ folders
- README.md in each chapter folder
- Tests passing for all code
- Version compatibility verified
- No hardcoded credentials or secrets
- Checklist: code-testing-checklist.md
learning_requirements:
- Learning objectives for each chapter
- Objectives use action verbs
- Measurable outcomes defined
- Progression from simple to complex
- Hands-on project focus
- Checklist: learning-objectives-checklist.md
handoff_prompts:
editor_to_curator: "Format validation complete. {{chapter_count}} chapters meet PacktPub SharePoint requirements. All structural elements present (What You'll Learn, Prerequisites, Summary, Q&A). Code validation in progress."
curator_to_designer: "Code validation complete. {{example_count}} code examples tested and passing. Repository structure meets PacktPub standards. Learning objectives extraction in progress."
designer_to_publisher: "Learning objectives summary created. {{objective_count}} total objectives across {{chapter_count}} chapters. Clear learning progression demonstrated. Ready for submission package preparation."
publisher_validation: "Submission package prepared. Structure: ChapterFiles ({{chapter_count}} chapters), CodeFiles ({{example_count}} examples), ImageFiles ({{image_count}} images). Running final validation checklist."
ready_for_submission: "PacktPub submission package complete and validated. All quality gates passed. Package ready for SharePoint upload. Location: submission-package/packtpub-submission/"
packtpub_specific_requirements:
chapter_structure:
- What You Will Learn section (bullet points)
- Prerequisites section
- Main content sections
- Summary section (key takeaways)
- Q&A section (5-10 questions)
- Further reading (optional)
formatting:
- SharePoint-compatible format preferred
- Code blocks with language identifiers
- Callout boxes: Note, Tip, Warning, Important
- Screenshot captions: "Figure X.Y: Description"
- Numbered lists for procedures
- Bold for UI elements, italic for emphasis
code_repository:
- GitHub repository required
- Folder per chapter: chapter-01/, chapter-02/
- README.md in each folder with setup instructions
- requirements.txt or package.json for dependencies
- All code tested and working
- .gitignore for temporary files
images:
- High resolution (300 DPI minimum)
- PNG or JPEG format
- Clear, readable text in screenshots
- Annotations for important areas
- Filename convention: chapterXX-figureYY-description.png
time_estimates:
format_validation: "2-4 hours (depends on chapter count)"
code_validation: "3-6 hours (depends on code complexity)"
learning_objectives: "2-3 hours"
package_preparation: "2-4 hours"
final_validation: "1-2 hours"
total_time: "10-19 hours"
best_practices:
- Start format validation early (don't wait until end)
- Test all code in fresh environment before submission
- Learning objectives should match chapter content exactly
- Use PacktPub style guide for formatting consistency
- Keep code examples practical and hands-on
- Screenshot quality matters - retake blurry images
- Q&A questions should test chapter learning objectives
- Maintain consistent terminology across all chapters
- Verify all external links work
- Double-check author questionnaire accuracy
common_pitfalls:
- Missing "What You Will Learn" section (required by PacktPub)
- Code examples not tested (failures during review)
- Low-resolution screenshots (unusable in print)
- Inconsistent chapter structure
- Missing Q&A sections
- Code repository not organized by chapter
- Hardcoded credentials in code examples
- Vague learning objectives (not measurable)
- Missing prerequisites in chapters
- Incomplete author questionnaire

234
expansion-packs/bmad-technical-writing/workflows/self-publishing-workflow.yaml Normal file
View File

@ -0,0 +1,234 @@
workflow:
id: self-publishing-workflow
name: Prepare for Self-Publishing
description: Package manuscript for self-publishing platforms (Leanpub, Amazon KDP, Gumroad). Supports multiple formats (markdown, DOCX, PDF), platform-specific optimization, metadata preparation, and pricing strategy.
type: publisher-submission
version: 1.0
project_types:
- technical-book
publisher: Self-Publishing (Leanpub/KDP/Gumroad)
sequence:
- agent: book-publisher
decides: platform-selection.md
requires: book-goals, target-audience
notes: "Choose self-publishing platform based on goals. Leanpub: Iterative publishing, markdown-based, developer audience. Amazon KDP: Wide distribution, royalties, print-on-demand. Gumroad: Direct sales, flexible pricing, no approval process. Can use multiple platforms simultaneously. SAVE OUTPUT: platform-strategy.md"
- agent: book-publisher
creates: formatted-manuscript/
requires: manuscript-chapters[], platform-selection
notes: "Format manuscript for target platform(s). Leanpub: Markdown with Leanpub extensions. KDP: Word .docx with styles, page breaks, TOC. Gumroad: PDF (professional typesetting). Optimize for platform requirements. SAVE OUTPUT: formatted-manuscript/{{platform}}/"
- agent: book-publisher
optimizes: images/
requires: book-images[]
notes: "Optimize images for each platform. Leanpub: PNG/JPEG, any DPI (responsive). KDP: 300 DPI minimum for print, RGB for Kindle. Gumroad: High-quality PDF-embedded images. Compress file sizes without quality loss. SAVE OUTPUT: optimized-images/{{platform}}/"
- agent: book-publisher
creates: metadata-package.md
requires: formatted-manuscript/
notes: "Create platform metadata. Title, subtitle, description (sales copy), author bio, keywords (SEO), categories, pricing, cover image requirements. Each platform has different metadata fields and character limits. SAVE OUTPUT: metadata/{{platform}}-metadata.yaml"
- agent: technical-editor
validates: platform-format.md
requires: formatted-manuscript/, metadata-package
notes: "Validate format meets platform requirements. Leanpub: Valid markdown, book.txt manifest, preview builds. KDP: Word .docx passes KDP validator, no formatting errors. Gumroad: PDF renders correctly, bookmarks work, links functional. SAVE OUTPUT: format-validation-{{platform}}.md"
- agent: book-publisher
creates: publication-package/
requires: format-validated
notes: "Finalize publication package for each platform. Leanpub: manuscript/ folder with chapters, images/, book.txt. KDP: .docx file, cover image, metadata. Gumroad: PDF file, cover image, sales page copy. SAVE OUTPUT: publication-packages/{{platform}}/"
flow_diagram: |
```mermaid
graph TD
A[Start: Manuscript Ready] --> B[book-publisher: Choose Platform(s)]
B --> C{Which Platform?}
C -->|Leanpub| D[Format: Markdown]
C -->|Amazon KDP| E[Format: DOCX]
C -->|Gumroad| F[Format: PDF]
C -->|Multiple| G[Format: All Required]
D --> H[Optimize Images: Leanpub]
E --> I[Optimize Images: KDP Print/Kindle]
F --> J[Optimize Images: PDF]
G --> H
G --> I
G --> J
H --> K[Create Metadata: Leanpub]
I --> L[Create Metadata: KDP]
J --> M[Create Metadata: Gumroad]
K --> N[technical-editor: Validate Leanpub]
L --> O[technical-editor: Validate KDP]
M --> P[technical-editor: Validate Gumroad]
N --> Q{Valid?}
O --> R{Valid?}
P --> S{Valid?}
Q -->|No| T[Fix Leanpub Issues]
R -->|No| U[Fix KDP Issues]
S -->|No| V[Fix Gumroad Issues]
T --> N
U --> O
V --> P
Q -->|Yes| W[Finalize Leanpub Package]
R -->|Yes| X[Finalize KDP Package]
S -->|Yes| Y[Finalize Gumroad Package]
W --> Z[Publish]
X --> Z
Y --> Z
style Z fill:#90EE90
style B fill:#FFE4B5
style D fill:#ADD8E6
style E fill:#ADD8E6
style F fill:#ADD8E6
```
platform_comparison:
leanpub:
format: "Markdown with Leanpub extensions"
distribution: "Leanpub marketplace only"
pricing: "Minimum/suggested/maximum flexible pricing"
royalties: "80% (minus 50¢ transaction fee)"
audience: "Developers, technical readers"
unique_features: "Iterative publishing, in-progress sales, variable pricing"
best_for: "Technical books, frequent updates, building in public"
amazon_kdp:
format: "Word .docx (Kindle), PDF or .docx (print)"
distribution: "Amazon worldwide, Kindle devices/apps"
pricing: "Fixed price or KDP Select (Kindle Unlimited)"
royalties: "35% or 70% (based on price), print cost deduction"
audience: "General public, wide reach"
unique_features: "Huge distribution, print-on-demand, KDP Select benefits"
best_for: "Maximum reach, print versions, broad audience"
gumroad:
format: "PDF (or any digital format)"
distribution: "Direct sales (your audience, your marketing)"
pricing: "Fully flexible, can include tiers, bundles"
royalties: "90% (10% Gumroad fee)"
audience: "Your existing audience, mailing list"
unique_features: "Direct relationship with buyers, flexible pricing, bundles"
best_for: "Building audience, premium pricing, bundled offers"
quality_gates:
format_requirements:
leanpub:
- Valid Leanpub-flavored markdown
- book.txt manifest lists all chapters
- Images in images/ folder
- Frontmatter and mainmatter sections
- Preview builds without errors
- Links and cross-references work
kdp:
- Word .docx with proper styles
- Table of contents auto-generated
- Page breaks before chapters
- Images embedded (not linked)
- Passes KDP file validator
- Cover image: 2560×1600 px minimum, JPEG/TIFF
gumroad:
- Professional PDF with bookmarks
- Embedded fonts (no missing font errors)
- Hyperlinks functional
- Table of contents bookmarks
- Optimized file size (<50 MB ideal)
- Cover page attractive
metadata_requirements:
all_platforms:
- Compelling title and subtitle
- Sales description (hook readers)
- Author bio (credibility)
- Keywords for discoverability
- Category selection
- Cover image (professional quality)
- Pricing strategy
handoff_prompts:
publisher_platform: "Platform selection complete. Target platform(s): {{platforms}}. Strategy: {{strategy}}. Leanpub for iterative updates, KDP for wide distribution, Gumroad for premium pricing. Formatting in progress for {{platform_count}} platform(s)."
publisher_format: "Formatting complete for {{platform}}. {{chapter_count}} chapters formatted. Leanpub: {{markdown_files}} markdown files. KDP: {{docx_status}}. Gumroad: {{pdf_status}}. Image optimization in progress."
publisher_images: "Image optimization complete. {{image_count}} images optimized for {{platform}}. Leanpub: Responsive sizing. KDP: 300 DPI print-ready. Gumroad: High-quality PDF-embedded. Metadata preparation in progress."
publisher_metadata: "Metadata package created for {{platform}}. Title: {{title}}. Subtitle: {{subtitle}}. Description: {{description_length}} characters. {{keyword_count}} keywords. Categories: {{categories}}. Pricing: {{pricing}}. Format validation in progress."
editor_validation: "Format validation complete for {{platform}}. Status: {{validation_status}}. {{issue_count}} issues found. Leanpub preview builds: {{leanpub_status}}. KDP validator: {{kdp_status}}. Gumroad PDF rendering: {{gumroad_status}}."
publisher_package: "Publication package finalized for {{platform}}. Location: publication-packages/{{platform}}/. Includes: {{package_contents}}. Ready for {{platform}} upload and publication."
platform_specific_details:
leanpub_workflow:
- Create manuscript/ folder structure
- Write book.txt manifest (lists chapter order)
- Use Leanpub markdown extensions (A>, T>, etc.)
- Preview book (builds PDF, EPUB, MOBI)
- Set minimum/suggested/maximum pricing
- Publish to Leanpub marketplace
- Update manuscript, click "Publish New Version"
- Readers get updates automatically
kdp_workflow:
- Format manuscript in Word with styles
- Generate automatic table of contents
- Upload .docx to KDP (Kindle) or PDF (print)
- Upload cover image (KDP Cover Creator or custom)
- Enter metadata (title, description, keywords)
- Set pricing (35% or 70% royalty)
- KDP Select (exclusive) or wide distribution
- Preview with Kindle Previewer
- Publish (24-48 hour review)
- Updates require re-uploading and re-publishing
gumroad_workflow:
- Create professional PDF (use Pandoc, LaTeX, InDesign)
- Optimize PDF file size
- Design sales page (Gumroad product page)
- Upload PDF to Gumroad
- Set pricing (single price or tiers)
- Create cover/preview images
- Write compelling product description
- Optional: Bundles (book + code + videos)
- Publish immediately (no approval process)
- Updates: Replace PDF file, notify customers
time_estimates:
platform_selection: "1-2 hours (research and strategy)"
leanpub_formatting: "4-6 hours (markdown conversion)"
kdp_formatting: "8-12 hours (Word styling, print formatting)"
gumroad_pdf_creation: "10-15 hours (professional typesetting)"
image_optimization: "2-4 hours (per platform)"
metadata_creation: "2-3 hours (per platform)"
format_validation: "2-3 hours (per platform)"
package_finalization: "1-2 hours (per platform)"
total_single_platform: "14-25 hours (Leanpub fastest)"
total_all_platforms: "30-50 hours"
best_practices:
- Start with Leanpub for fast market validation
- Add KDP for wider distribution after Leanpub success
- Use Gumroad for premium bundles (book + code + extras)
- Professional cover design matters (hire designer)
- Metadata keywords crucial for discoverability
- Price testing: Leanpub's variable pricing helps find sweet spot
- Build email list (own your audience)
- Iterative publishing on Leanpub builds momentum
- KDP Select benefits if exclusive is acceptable
- Gumroad bundles justify higher pricing
common_pitfalls:
- Poor cover design (readers judge books by covers)
- Weak sales description (first impression matters)
- Wrong pricing (too low devalues, too high reduces sales)
- No marketing plan (build audience before launch)
- Ignoring metadata/keywords (discoverability suffers)
- Format errors (unprofessional, bad reviews)
- No email list (can't reach buyers for updates)
- Platform exclusivity without strategy (limits options)
- No updates/revisions (technical books age quickly)
- Overlooking international pricing (currency matters)