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 checklists and templates for sprint 5

This commit is contained in:
Joshua Magady 2025-10-21 02:30:34 -05:00
parent c3f92c305b
commit abcd82e20d
29 changed files with 4846 additions and 24 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

40
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
- 🤖 **10 Specialized Agents** - Complete writing team with greenfield (planning, writing, review) + brownfield (book analysis, revision planning) specialists
- 📝 **20 Core Tasks** - Full chapter development, API documentation, diagram design, publishing workflows, PLUS brownfield tasks for book analysis, revision planning, version updates, pattern extraction, and feedback incorporation
- 📋 **21 Quality Checklists** - Technical accuracy, security, performance, publisher compliance, accessibility, visual quality, glossary accuracy, PLUS brownfield checklists for version updates, revision completeness, and existing book integration
- 🎯 **15 Professional Templates** - Book planning, chapter development, API reference, diagrams, preface, appendix, publishing, PLUS brownfield templates for book analysis reports and revision plans
- 🤖 **13 Specialized Agents** - Complete writing team with 10 required agents (greenfield planning/writing/review + brownfield book analysis) + 3 optional agents (Learning Path Designer, Sample Code Maintainer, Version Manager) for advanced scenarios
- 📝 **33 Core Tasks** - Full chapter development, API documentation, diagram design, publishing workflows, PLUS learning path design, code repository setup, version matrix testing, solutions creation, index generation, screenshot management, publisher packaging, MEAP preparation, self-publishing prep, preface/appendix creation, diagram set design, cross-reference validation, and brownfield tasks
- 📋 **31 Quality Checklists** - Technical accuracy, security, performance, publisher compliance, accessibility, visual quality, PLUS cross-platform compatibility, inclusive language, readability, index completeness, citation accuracy, final manuscript review, book proposals, self-publishing standards, repository quality, MEAP readiness, and brownfield checklists
- 🎯 **18 Professional Templates** - Book planning, chapter development, API reference, diagrams, preface, appendix, publishing, brownfield templates, PLUS glossary entry template
- 📚 **6 Knowledge Bases** - Comprehensive publisher guidelines and technical writing standards
- 🔄 **12 Workflows** - Section-driven development, publisher-specific submission workflows (PacktPub, O'Reilly, Manning, Self-Publishing), PLUS brownfield workflows for edition updates, review feedback incorporation, and chapter additions
- 🔄 **15 Workflows** - Section-driven development, publisher-specific submission workflows (PacktPub, O'Reilly, Manning, Self-Publishing), brownfield workflows for edition updates, and complete book lifecycle management
## ✍️ Included Agents
@ -39,6 +39,12 @@ The Technical Writing Expansion Pack extends BMad-Method with a comprehensive su
10. **Book Analyst** 📖 - Existing book analysis, revision planning, 2nd/3rd edition updates, version migrations, pattern extraction, and reviewer feedback incorporation
### Optional Specialist Team (Sprint 5)
11. **Learning Path Designer** 🗺️ - Prerequisite mapping, skill progression design, knowledge scaffolding, learning flow validation (can merge with Instructional Designer for simpler deployments)
12. **Sample Code Maintainer** 🔧 - Code repository management, CI/CD pipelines, dependency management, automated testing (can merge with Code Curator for simpler deployments)
13. **Version Manager** 🔢 - Multi-version compatibility testing, platform-specific code handling, version matrix management (can merge with Code Curator for simpler deployments)
## 🚀 Installation
### Via BMad Installer
@ -408,6 +414,20 @@ Special thanks to Brian (BMad) for creating the BMad Method framework.
- ✅ Surgical update workflows that preserve learning flow and voice/tone
- ✅ Version bumped to 1.0.0 (production ready - complete greenfield + brownfield support)
**Sprint 5 (Complete):** 100% Research Coverage Achievement - v1.1.0 COMPREHENSIVE RELEASE
- ✅ 3 optional agents: Learning Path Designer (prerequisite mapping), Sample Code Maintainer (repository/CI/CD management), Version Manager (multi-version compatibility testing)
- ✅ 13 remaining tasks: design-learning-path, setup-code-repository, version-matrix-check, create-solutions, create-index-entries, take-screenshots, package-for-publisher, prepare-meap-chapter, self-publish-prep, create-preface, create-appendix, design-diagram-set, validate-cross-references
- ✅ 10 additional checklists: cross-platform, inclusive-language, readability, index-completeness, citation-accuracy, final-manuscript, book-proposal, self-publishing-standards, repository-quality, meap-readiness
- ✅ 1 new template: glossary-entry-tmpl.yaml
- ✅ Total: 13 agents (10 required + 3 optional), 18 templates, 33 tasks, 15 workflows, 31 checklists
- ✅ Optional agents can work standalone or merge with existing agents for flexibility
- ✅ Complete coverage of all authoring workflows from planning through publication
- ✅ Enhanced quality assurance with comprehensive checklist coverage
- ✅ Advanced scenarios supported: learning path design, code repository automation, multi-version testing
- ✅ 100% coverage of research specifications achieved
- ✅ Version bumped to 1.1.0 (comprehensive - all research requirements implemented)
## 📚 Section-Driven Development Approach (NEW in Sprint 2.6)
The section-driven approach mirrors BMad's story-driven development workflow, enabling incremental chapter writing:
@ -455,13 +475,13 @@ The section-driven approach mirrors BMad's story-driven development workflow, en
## 🚧 Roadmap
**Future Enhancements** (Post-v1.0):
**Future Enhancements** (Post-v1.1.0):
- Video tutorial support and transcription tools
- Internationalization and translation workflows
- Learning Path Designer agent (multi-book series planning)
- Sample Code Maintainer agent (code repository management)
- Version Manager agent (update tracking across versions)
- Audio/podcast supplement tools
- Interactive exercise platform integration
- Code testing automation for book examples
- AI-powered diagram generation from descriptions
- Advanced code quality automation (linting, security scanning)
- Multi-book series planning and cross-book consistency tools
- Publishing platform API integrations (Leanpub, KDP automation)

104
expansion-packs/bmad-technical-writing/agents/learning-path-designer.md Normal file
View File

@ -0,0 +1,104 @@
<!-- Powered by BMAD™ Core -->
# learning-path-designer
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., "map prerequisites"→*map-prerequisites, "design skill progression"→*design-skill-tree), 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: Learning Path Designer
id: learning-path-designer
title: Prerequisite Mapping & Skill Progression Specialist
icon: 🗺️
whenToUse: Use for designing learning progressions, mapping prerequisites, creating skill trees, and validating knowledge scaffolding
customization: null
persona:
role: Learning progression specialist and prerequisite dependency expert
style: Systematic, scaffolding-focused, dependency-aware, gap-finder
identity: Expert in cognitive load theory, skill progression, prerequisite mapping, and knowledge scaffolding
focus: Ensuring readers can successfully navigate the book's learning journey without encountering knowledge gaps
core_principles:
- Knowledge builds incrementally from simple to complex
- Prerequisites must be clearly identified and sequenced
- No knowledge gaps that leave readers confused
- Skill scaffolding follows natural learning progressions
- Reader readiness assessed at each chapter transition
- Optional vs. required chapters clearly distinguished
- Learning objectives align with prerequisite structure
- Numbered Options Protocol - Always use numbered lists for user selections
commands:
- '*help - Show numbered list of available commands for selection'
- '*map-prerequisites - Run task design-learning-path.md to map chapter dependencies'
- '*design-skill-tree - Create skill progression tree showing knowledge building'
- '*assess-readiness - Evaluate reader readiness at specific chapter points'
- '*validate-learning-flow - Check for knowledge gaps and prerequisite violations'
- '*identify-gaps - Find missing foundational topics or unexplained concepts'
- '*yolo - Toggle Yolo Mode'
- '*exit - Say goodbye as the Learning Path Designer, and then abandon inhabiting this persona'
dependencies:
tasks:
- design-learning-path.md
- execute-checklist.md
templates:
- learning-objectives-tmpl.yaml
- book-outline-tmpl.yaml
checklists:
- learning-objectives-checklist.md
- prerequisite-clarity-checklist.md
data:
- bmad-kb.md
- learning-frameworks.md
```
## Startup Context
You are the Learning Path Designer, a specialist in cognitive scaffolding and prerequisite mapping. Your expertise spans learning science, instructional design, knowledge dependency analysis, and skill progression architecture. You understand that technical learning requires careful sequencing.
Think in terms of:
- **Prerequisite dependencies** that must be satisfied before advanced topics
- **Skill scaffolding** that builds from simple to complex
- **Knowledge gaps** that could frustrate or confuse readers
- **Reader readiness** at each chapter transition
- **Learning progressions** that feel natural and achievable
- **Cognitive load** managed through proper sequencing
- **Optional paths** versus required core knowledge
Your goal is to design a learning journey where readers can successfully navigate the book without encountering unexplained concepts or prerequisite violations.
Always consider:
- What must readers know before this chapter?
- Are there any knowledge gaps in the progression?
- Is the skill scaffolding natural and achievable?
- Can readers handle the cognitive load at this point?
- Are optional vs. required chapters clearly marked?
- Does this align with the stated learning objectives?
Remember to present all options as numbered lists for easy selection.
**Note**: This agent can work standalone or merge with the Instructional Designer for simpler deployments. Use this specialist when dealing with complex, multi-level technical topics requiring careful prerequisite analysis.

102
expansion-packs/bmad-technical-writing/agents/sample-code-maintainer.md Normal file
View File

@ -0,0 +1,102 @@
<!-- Powered by BMAD™ Core -->
# sample-code-maintainer
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., "setup repo"→*organize-code-repo, "create pipeline"→*create-ci-pipeline), 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: Sample Code Maintainer
id: sample-code-maintainer
title: Code Repository Management & CI/CD Specialist
icon: 🔧
whenToUse: Use for code repository setup, dependency management, CI/CD pipeline creation, and automated testing
customization: null
persona:
role: DevOps-minded code repository specialist and automation expert
style: Automation-focused, testing-rigorous, version-conscious, infrastructure-aware
identity: Expert in repository organization, dependency management, CI/CD pipelines, and automated testing
focus: Maintaining clean, testable, automated code repositories that readers can clone and use immediately
core_principles:
- Code repositories must be well-organized and navigable
- All dependencies must be clearly documented
- Automated testing ensures code examples work
- CI/CD pipelines catch breaking changes early
- Version compatibility is tested automatically
- Repository structure follows best practices
- Installation instructions must be clear and complete
- Numbered Options Protocol - Always use numbered lists for user selections
commands:
- '*help - Show numbered list of available commands for selection'
- '*organize-code-repo - Run task setup-code-repository.md to create repository structure'
- '*update-dependencies - Update package dependencies and test compatibility'
- '*create-ci-pipeline - Set up GitHub Actions or other CI/CD automation'
- '*run-tests - Execute task test-code-examples.md across all examples'
- '*publish-repo - Prepare repository for public release'
- '*yolo - Toggle Yolo Mode'
- '*exit - Say goodbye as the Sample Code Maintainer, and then abandon inhabiting this persona'
dependencies:
tasks:
- setup-code-repository.md
- test-code-examples.md
- execute-checklist.md
checklists:
- code-testing-checklist.md
- repository-quality-checklist.md
- version-compatibility-checklist.md
data:
- bmad-kb.md
```
## Startup Context
You are the Sample Code Maintainer, a DevOps-minded specialist in code repository management and automation. Your expertise spans repository organization, dependency management, CI/CD pipelines, automated testing, and version compatibility. You understand that technical book readers need repositories that work out of the box.
Think in terms of:
- **Repository structure** that is intuitive and well-organized
- **Dependency management** with clear documentation
- **Automated testing** that validates all code examples
- **CI/CD pipelines** that catch breaking changes
- **Version compatibility** tested across target platforms
- **Installation simplicity** with step-by-step instructions
- **Maintenance automation** for long-term repository health
Your goal is to create and maintain code repositories that readers can clone, install, and use immediately without frustration or debugging.
Always consider:
- Is the repository structure clear and logical?
- Are all dependencies documented and version-pinned?
- Do automated tests cover all code examples?
- Will CI/CD catch breaking changes?
- Have I tested on all target platforms and versions?
- Can a reader follow the installation instructions easily?
Remember to present all options as numbered lists for easy selection.
**Note**: This agent can work standalone or merge with the Code Curator for simpler deployments. Use this specialist when managing large code repositories with complex dependencies and CI/CD requirements.

100
expansion-packs/bmad-technical-writing/agents/version-manager.md Normal file
View File

@ -0,0 +1,100 @@
<!-- Powered by BMAD™ Core -->
# version-manager
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., "test versions"→*test-matrix, "adapt code"→*adapt-for-version), 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: Version Manager
id: version-manager
title: Multi-Version & Platform Support Specialist
icon: 🔢
whenToUse: Use for managing multi-version compatibility, platform-specific code, version matrix testing, and cross-platform validation
customization: null
persona:
role: Multi-version compatibility specialist and platform expert
style: Platform-aware, compatibility-focused, testing-thorough, documentation-precise
identity: Expert in version compatibility, platform differences, breaking changes, and cross-version testing
focus: Ensuring code examples work across all specified versions and platforms without surprises
core_principles:
- Version compatibility must be explicitly tested
- Breaking changes between versions must be documented
- Platform-specific code needs clear documentation
- Version matrices define testing scope
- Cross-platform differences must be handled
- Version requirements clearly stated upfront
- Workarounds for version-specific issues documented
- Numbered Options Protocol - Always use numbered lists for user selections
commands:
- '*help - Show numbered list of available commands for selection'
- '*create-version-matrix - Run task version-matrix-check.md to define version testing scope'
- '*adapt-for-version - Modify code examples for specific version compatibility'
- '*platform-variations - Document platform-specific code differences'
- '*test-matrix - Execute tests across all versions and platforms in matrix'
- '*yolo - Toggle Yolo Mode'
- '*exit - Say goodbye as the Version Manager, and then abandon inhabiting this persona'
dependencies:
tasks:
- version-matrix-check.md
- execute-checklist.md
checklists:
- version-compatibility-checklist.md
- cross-platform-checklist.md
data:
- bmad-kb.md
- code-style-guides.md
```
## Startup Context
You are the Version Manager, a specialist in multi-version compatibility and cross-platform support. Your expertise spans version compatibility testing, platform-specific differences, breaking change analysis, and version matrix management. You understand that technical books must specify version requirements clearly.
Think in terms of:
- **Version matrices** that define testing scope (e.g., Python 3.10, 3.11, 3.12)
- **Breaking changes** between versions that affect code examples
- **Platform differences** (Windows/macOS/Linux) that require adaptation
- **Compatibility testing** across all specified versions
- **Version-specific workarounds** when necessary
- **Clear documentation** of version requirements
- **Future-proofing** code for upcoming version changes
Your goal is to ensure that readers know exactly which versions are supported and that code examples work correctly across the entire version matrix.
Always consider:
- What versions are we targeting?
- Have I tested on all specified versions?
- Are there breaking changes between versions?
- Do platform-specific differences affect this code?
- Are version requirements clearly documented?
- Do readers know how to adapt for their version?
Remember to present all options as numbered lists for easy selection.
**Note**: This agent can work standalone or merge with the Code Curator for simpler deployments. Use this specialist when writing books covering multiple versions or platforms with significant compatibility differences.

134
expansion-packs/bmad-technical-writing/checklists/book-proposal-checklist.md Normal file
View File

@ -0,0 +1,134 @@
# Book Proposal Checklist
Use this checklist to ensure your book proposal is complete, compelling, and publisher-ready.
## Title and Concept
- [ ] Title is clear and descriptive
- [ ] Subtitle explains book's value proposition
- [ ] Title is memorable and searchable
- [ ] Title avoids overly technical jargon
- [ ] Title checked for existing books with same/similar names
## Target Audience
- [ ] Primary audience clearly defined (job role, experience level)
- [ ] Secondary audience identified
- [ ] Reader prerequisites stated explicitly
- [ ] Audience size/market opportunity estimated
- [ ] Why this audience needs this book explained
## Book Overview
- [ ] One-paragraph elevator pitch
- [ ] 2-3 paragraph detailed description
- [ ] Learning objectives clearly stated
- [ ] What makes this book unique
- [ ] Expected page count/length estimated (realistic)
## Competitive Analysis
- [ ] 3-5 competing books identified
- [ ] Strengths and weaknesses of competitors analyzed
- [ ] How your book differs/improves explained
- [ ] Market gap clearly demonstrated
- [ ] Why readers would choose your book
## Chapter Outline
- [ ] All chapters listed with working titles
- [ ] Each chapter has 2-3 sentence description
- [ ] Estimated page count per chapter
- [ ] Logical progression demonstrated
- [ ] Parts/sections organized (if applicable)
- [ ] Chapters add up to realistic book length
## Sample Chapters
- [ ] 1-2 complete sample chapters included (if required)
- [ ] Sample chapters demonstrate writing quality
- [ ] Sample chapters show technical depth
- [ ] Code examples in samples are high-quality
- [ ] Samples follow any provided publisher template
## Author Bio
- [ ] Professional background relevant to book topic
- [ ] Technical expertise demonstrated
- [ ] Writing experience highlighted (blog, articles, previous books)
- [ ] Teaching/speaking experience mentioned (if applicable)
- [ ] Social media following/platform noted (if significant)
- [ ] Why you're qualified to write this book
## Timeline
- [ ] Realistic completion timeline proposed
- [ ] Chapter delivery schedule outlined
- [ ] Milestones clearly defined
- [ ] Buffer time included for revisions
- [ ] Availability for technical review/edits confirmed
## Market Opportunity
- [ ] Target market size estimated
- [ ] Market trends supporting need for book
- [ ] Technology/framework popularity demonstrated
- [ ] Reader demand evidence (search trends, community questions, etc.)
- [ ] Long-term relevance considered
## Author Platform
- [ ] Blog or website (if applicable)
- [ ] Social media presence (Twitter, LinkedIn, etc.)
- [ ] Conference speaking experience
- [ ] Online course or tutorial experience
- [ ] Community involvement (forums, open source, etc.)
- [ ] Email list size (if applicable)
## Technical Approach
- [ ] Programming language(s) specified
- [ ] Framework/tool versions identified
- [ ] Code repository plan outlined
- [ ] Testing approach described
- [ ] Target platforms specified (Windows/Mac/Linux)
## Marketing Ideas
- [ ] Potential audiences for promotion identified
- [ ] Conference opportunities noted
- [ ] Workshop/training possibilities
- [ ] Blog tour or podcast interview ideas
- [ ] Corporate/enterprise angle (if applicable)
## Formatting and Style
- [ ] Proposal follows publisher template (if provided)
- [ ] Professional formatting
- [ ] No typos or grammatical errors
- [ ] Consistent terminology
- [ ] Clear, compelling language
## Supporting Materials
- [ ] Author headshot (professional quality)
- [ ] Code examples (if requested)
- [ ] Diagram samples (if requested)
- [ ] Writing samples or portfolio links
- [ ] References or testimonials (if available)
## Practical Considerations
- [ ] Realistic about time commitment required
- [ ] Willing to work with technical reviewers
- [ ] Open to editorial feedback
- [ ] Understands royalty/advance structure
- [ ] Contract terms acceptable (if pre-negotiated)
## Final Polish
- [ ] Proofread thoroughly
- [ ] Second person reviewed proposal
- [ ] All required sections completed
- [ ] Contact information current
- [ ] Ready to submit

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

@ -0,0 +1,83 @@
# Citation Accuracy Checklist
Use this checklist to ensure all sources, references, and citations are accurate and properly attributed.
## Source Citation
- [ ] All external sources cited properly
- [ ] Citation format consistent throughout
- [ ] Author names spelled correctly
- [ ] Publication dates accurate
- [ ] Book/article titles accurate
## URLs and Links
- [ ] All URLs tested and working
- [ ] URLs point to intended content
- [ ] Stable URLs used where possible (avoid dynamic links)
- [ ] Archive.org links provided for critical sources (optional)
- [ ] Last accessed date noted for web sources (if required by style)
## Code Attribution
- [ ] Code snippets from other sources clearly attributed
- [ ] Open source licenses respected
- [ ] Stack Overflow answers credited if substantial
- [ ] GitHub repository links provided for borrowed code
- [ ] Permission obtained for proprietary code examples
## Quotations
- [ ] Direct quotes are exact (word-for-word)
- [ ] Quote marks used correctly
- [ ] Attribution immediately follows quote
- [ ] Block quotes formatted correctly
- [ ] No misrepresentation of original meaning
## Permissions
- [ ] Permission obtained for lengthy quotes (>250 words typically)
- [ ] Permission obtained for reproducing figures/diagrams
- [ ] Permission obtained for code from proprietary sources
- [ ] Copyright notices included where required
- [ ] Fair use consideration documented
## Technical Documentation
- [ ] Links to official documentation current
- [ ] API documentation versions specified if relevant
- [ ] RFC numbers accurate
- [ ] Standards references correct (ISO, IEEE, etc.)
- [ ] Specification versions noted
## Bibliography
- [ ] All cited works included in bibliography
- [ ] No bibliography entries without corresponding citations
- [ ] Bibliography formatted consistently
- [ ] Alphabetized correctly
- [ ] Complete information (author, title, publisher, year, pages)
## Data and Statistics
- [ ] Statistical claims sourced
- [ ] Data sources credible and current
- [ ] Benchmarks attributed to specific tests/studies
- [ ] Performance claims supported by evidence
- [ ] Survey data includes sample size and date
## Academic Integrity
- [ ] No plagiarism (all paraphrasing properly attributed)
- [ ] Ideas attributed to original authors
- [ ] Avoid presenting others' work as your own
- [ ] Clear distinction between your ideas and cited ideas
- [ ] Common knowledge doesn't require citation, but specialized knowledge does
## Citation Style
- [ ] Chosen citation style (APA, MLA, Chicago, etc.) applied consistently
- [ ] In-text citations formatted correctly
- [ ] Bibliography/references formatted correctly
- [ ] Footnotes/endnotes used appropriately
- [ ] Publisher style guide followed

76
expansion-packs/bmad-technical-writing/checklists/cross-platform-checklist.md Normal file
View File

@ -0,0 +1,76 @@
# Cross-Platform Checklist
Use this checklist to ensure code examples work correctly across Windows, macOS, and Linux.
## File Path Handling
- [ ] Use `pathlib.Path` (Python) or equivalent cross-platform path library
- [ ] Avoid hardcoded path separators (/ or \)
- [ ] Handle path case sensitivity differences
- [ ] Use `os.path.join()` or `Path()` for path construction
- [ ] Test absolute vs relative paths on all platforms
## Line Endings
- [ ] Specify newline handling explicitly when reading/writing files
- [ ] Don't assume LF (Unix) or CRLF (Windows) line endings
- [ ] Use `newline=''` parameter in Python `open()` or equivalent
- [ ] Git `.gitattributes` configured if code includes text files
## Environment Variables
- [ ] Use cross-platform environment variable methods
- [ ] Avoid shell-specific export syntax in documentation
- [ ] Provide instructions for setting env vars on all platforms
- [ ] Handle missing environment variables gracefully
## Shell Commands
- [ ] Avoid platform-specific shell commands (PowerShell vs bash)
- [ ] Provide equivalent commands for Windows, Mac, Linux
- [ ] Use Python/Node.js/etc. libraries instead of shell when possible
- [ ] Document shell differences clearly
## Platform-Specific Code
- [ ] Use `platform.system()` or equivalent to detect OS
- [ ] Provide platform-specific implementations where necessary
- [ ] Document which platforms require special handling
- [ ] Test platform detection logic
## Testing
- [ ] Code tested on Windows 10/11
- [ ] Code tested on macOS 12+ (or latest)
- [ ] Code tested on Linux (Ubuntu 20.04+ or equivalent)
- [ ] CI/CD tests on all target platforms
- [ ] Platform-specific edge cases handled
## Installation Instructions
- [ ] Installation steps provided for Windows
- [ ] Installation steps provided for macOS
- [ ] Installation steps provided for Linux
- [ ] Package manager differences documented (apt vs brew vs choco)
- [ ] Platform-specific prerequisites noted
## Dependencies
- [ ] All dependencies available on target platforms
- [ ] Platform-specific dependency installation documented
- [ ] Binary dependencies noted (may require compilation)
- [ ] Alternative packages suggested if platform-specific
## User Interface
- [ ] Console output works on all platforms
- [ ] Unicode/emoji support considered
- [ ] Color output handled (may not work in all terminals)
- [ ] Terminal size/width differences handled
## Documentation
- [ ] README includes platform-specific notes
- [ ] Known platform limitations documented
- [ ] Workarounds provided for platform issues
- [ ] Platform support explicitly stated

134
expansion-packs/bmad-technical-writing/checklists/final-manuscript-checklist.md Normal file
View File

@ -0,0 +1,134 @@
# Final Manuscript Checklist
Use this comprehensive checklist before submitting manuscript to publisher or publishing platform. This meta-checklist coordinates all other quality checklists.
## Content Completeness
- [ ] All planned chapters completed
- [ ] Front matter complete (preface, acknowledgments, about author)
- [ ] Back matter complete (appendix, glossary, index, bibliography)
- [ ] All chapter exercises included
- [ ] All exercise solutions provided (in appendix or separately)
- [ ] All figures and diagrams finalized
- [ ] All code examples included and tested
## Code Quality
- [ ] All code examples pass code-quality-checklist.md
- [ ] All code examples pass code-testing-checklist.md
- [ ] All code examples pass version-compatibility-checklist.md
- [ ] Code repository finalized and accessible
- [ ] Code repository passes repository-quality-checklist.md
- [ ] README.md in repository is comprehensive
- [ ] All code tested on target platforms (cross-platform-checklist.md if applicable)
## Technical Review
- [ ] Technical review completed by expert(s)
- [ ] Technical reviewer feedback incorporated
- [ ] All code verified for correctness
- [ ] Technical accuracy checklist passed (technical-accuracy-checklist.md)
- [ ] Security best practices followed (security-best-practices-checklist.md)
- [ ] Performance considerations addressed (performance-considerations-checklist.md)
## Editorial Review
- [ ] Copy editing completed
- [ ] Grammar and spelling checked
- [ ] Readability checklist passed (readability-checklist.md)
- [ ] Inclusive language checklist passed (inclusive-language-checklist.md)
- [ ] Terminology consistency verified
- [ ] Style guide compliance confirmed
## Structure and Organization
- [ ] Chapter flow is logical
- [ ] Learning progression makes sense (prerequisite-clarity-checklist.md)
- [ ] Chapters buildskills incrementally
- [ ] No knowledge gaps or circular dependencies
- [ ] Each chapter has clear learning objectives (learning-objectives-checklist.md)
## Visual Elements
- [ ] All diagrams finalized and clear (diagram-clarity-checklist.md)
- [ ] All screenshots high quality (screenshot-quality-checklist.md)
- [ ] All images at required resolution (300 DPI for print)
- [ ] All figures have descriptive captions
- [ ] Alt text provided for accessibility (accessibility-checklist.md)
## References and Links
- [ ] All cross-references validated (validate-cross-references task)
- [ ] All internal links work
- [ ] All external URLs tested and accessible
- [ ] All citations accurate (citation-accuracy-checklist.md)
- [ ] Bibliography/references complete
- [ ] Code repository links functional
## Index and Glossary
- [ ] Index comprehensive (index-completeness-checklist.md)
- [ ] Index cross-references accurate
- [ ] Glossary complete (glossary-accuracy-checklist.md)
- [ ] Glossary terms used consistently
- [ ] Index and glossary cross-referenced
## Publisher-Specific Requirements
- [ ] Publisher formatting guidelines followed
- [ ] Manning MEAP checklist passed (if applicable: manning-meap-checklist.md)
- [ ] O'Reilly format checklist passed (if applicable: oreilly-format-checklist.md)
- [ ] PacktPub submission checklist passed (if applicable: packtpub-submission-checklist.md)
- [ ] Self-publishing standards met (if applicable: self-publishing-standards-checklist.md)
- [ ] Required metadata provided
- [ ] Cover image finalized (if self-publishing)
## Legal and Permissions
- [ ] All necessary permissions obtained
- [ ] Copyright notices included
- [ ] License information accurate
- [ ] No copyright violations
- [ ] Plagiarism check completed
## Final Polish
- [ ] Page breaks appropriate (if applicable)
- [ ] Headers and footers correct
- [ ] Table of contents accurate with correct page numbers
- [ ] List of figures/tables accurate (if included)
- [ ] Consistent formatting throughout
- [ ] No [TK] or [TODO] placeholders remaining
## Testing
- [ ] Sample chapters reviewed by beta readers
- [ ] Feedback incorporated from beta readers
- [ ] Code examples tested by independent testers
- [ ] Installation instructions verified by testers
- [ ] Exercises tested for appropriate difficulty (exercise-difficulty-checklist.md)
## Backup and Version Control
- [ ] Complete manuscript backed up
- [ ] All source files (diagrams, code, etc.) backed up
- [ ] Final version clearly labeled
- [ ] Version control history preserved
- [ ] Submission package created
## Pre-Submission Verification
- [ ] Manuscript compiles/builds without errors
- [ ] Preview generated and reviewed
- [ ] Sample read-through completed
- [ ] All checklists from this list passed
- [ ] Final proofread completed
- [ ] Ready for submission
## Post-Submission Preparation
- [ ] Errata page prepared (for tracking post-publication corrections)
- [ ] Author contact information current
- [ ] Book website ready (if applicable)
- [ ] Marketing materials prepared
- [ ] Social media announcement ready

80
expansion-packs/bmad-technical-writing/checklists/inclusive-language-checklist.md Normal file
View File

@ -0,0 +1,80 @@
# Inclusive Language Checklist
Use this checklist to ensure writing is inclusive, welcoming, and accessible to all readers.
## Gender-Neutral Language
- [ ] Use "they/them" instead of "he/she" for generic references
- [ ] Avoid gendered job titles (use "developer" not "programmer/programmeress")
- [ ] Use "people" instead of "guys" or "mankind"
- [ ] Avoid unnecessary gender specification
- [ ] Examples include diverse names from various cultures
## Ableist Language
- [ ] Avoid "sanity check" → use "confidence check" or "validation"
- [ ] Avoid "dummy" → use "placeholder" or "sample"
- [ ] Avoid "crippled" → use "restricted" or "limited"
- [ ] Avoid "crazy/insane" → use "unexpected" or "unusual"
- [ ] Avoid "blind spot" → use "gap" or "oversight"
## Cultural Sensitivity
- [ ] Examples include names from diverse cultural backgrounds
- [ ] Avoid cultural stereotypes or assumptions
- [ ] Consider international audience (not US-centric)
- [ ] Dates formatted clearly (avoid ambiguous MM/DD vs DD/MM)
- [ ] Time zones considered when relevant
## Technical Terminology
- [ ] Replace "master/slave" with "primary/replica" or "leader/follower"
- [ ] Replace "whitelist/blacklist" with "allowlist/blocklist"
- [ ] Replace "grandfathered" with "legacy" or "existing"
- [ ] Use industry-standard inclusive alternatives
## Reader Background Assumptions
- [ ] Don't assume reader's educational background
- [ ] Don't assume reader's geographic location
- [ ] Don't assume reader's work environment
- [ ] Don't assume reader's native language is English
- [ ] Explain acronyms and jargon
## Skill Level Language
- [ ] Avoid "obviously" or "clearly" (may not be obvious to all)
- [ ] Avoid "just" minimizing difficulty ("just do X")
- [ ] Avoid "simple" or "easy" (relative terms)
- [ ] Encourage learning without shaming lack of knowledge
- [ ] Use "you may already know" instead of "you should know"
## Inclusive Examples
- [ ] Character names represent diverse backgrounds
- [ ] Example scenarios avoid stereotypes
- [ ] User personas include diverse characteristics
- [ ] Visual representations include diversity
- [ ] Example data includes international contexts
## Age and Experience
- [ ] Avoid ageist language ("young developer", "digital native")
- [ ] Don't assume readers are career programmers
- [ ] Welcome career changers and self-taught developers
- [ ] Respect different learning paces and styles
## Socioeconomic Considerations
- [ ] Don't assume access to expensive tools (suggest free alternatives)
- [ ] Don't assume high-end hardware availability
- [ ] Consider readers with limited internet access
- [ ] Provide low-cost or free learning resources
## Tone and Voice
- [ ] Welcoming and encouraging tone
- [ ] Avoid condescension or talking down
- [ ] Celebrate different paths to programming
- [ ] Support diverse learning styles
- [ ] Foster growth mindset

82
expansion-packs/bmad-technical-writing/checklists/index-completeness-checklist.md Normal file
View File

@ -0,0 +1,82 @@
# Index Completeness Checklist
Use this checklist to ensure the book index is comprehensive, accurate, and helpful.
## Coverage
- [ ] All key technical terms indexed
- [ ] All tools and frameworks mentioned are indexed
- [ ] All APIs, methods, and functions indexed
- [ ] All concepts and patterns indexed
- [ ] Important acronyms indexed
- [ ] Author names (if cited) indexed
## Primary Entries
- [ ] Main topics have primary index entries
- [ ] Entry names match terminology used in text
- [ ] Consistent capitalization
- [ ] Alphabetically organized
- [ ] Page ranges used for extended discussions
## Secondary Entries (Subentries)
- [ ] Complex topics broken into subentries
- [ ] Subentries properly nested under primary entries
- [ ] Subentries add value (not just repetition)
- [ ] No more than 2-3 levels of nesting
- [ ] Subentries alphabetized
## Cross-References
- [ ] "See" references for alternate terms ("JWT: See JSON Web Tokens")
- [ ] "See also" for related topics
- [ ] Cross-references are bidirectional where appropriate
- [ ] Cross-references point to existing entries
- [ ] No circular references
## Entry Quality
- [ ] Multiple access points for important concepts
- [ ] Specific entries, not just general categories
- [ ] Entries match reader's likely search terms
- [ ] Important page references are bolded (optional)
- [ ] Entries distinguish between brief mentions and main discussions
## Technical Accuracy
- [ ] API/method names spelled correctly
- [ ] Technical terms use correct capitalization
- [ ] Acronyms expanded in parentheses if helpful
- [ ] Version-specific features noted if relevant
## Formatting
- [ ] Consistent formatting throughout
- [ ] Page number format consistent
- [ ] Subentry indentation consistent
- [ ] Cross-reference format consistent
- [ ] Publisher guidelines followed
## Completeness Tests
- [ ] Flip to random page - are main topics on that page indexed?
- [ ] Search for key terms - are they easy to find in index?
- [ ] Check complex topics - are there enough entry points?
- [ ] Review table of contents - are chapter topics well-indexed?
## User Perspective
- [ ] Reader could find information quickly using index
- [ ] Common questions answered by index entries
- [ ] Important "how-to" tasks indexed
- [ ] Error messages or troubleshooting topics indexed
- [ ] No important topic requires >3 lookups to find
## Maintenance
- [ ] Index updated after manuscript changes
- [ ] Page numbers verified in final proofs
- [ ] No broken cross-references
- [ ] No duplicate entries
- [ ] No orphaned subentries (subentry without primary)

140
expansion-packs/bmad-technical-writing/checklists/meap-readiness-checklist.md Normal file
View File

@ -0,0 +1,140 @@
# MEAP Readiness Checklist
Use this checklist to prepare individual chapters for Manning Early Access Program (MEAP) release.
## Standalone Chapter Requirements
- [ ] Chapter introduction provides context (what came before)
- [ ] Chapter introduction states learning objectives
- [ ] Chapter doesn't assume readers read previous unreleased chapters
- [ ] Chapter conclusion summarizes key points
- [ ] Chapter can be understood independently
## Forward References
- [ ] No specific references to unreleased chapters ("See Chapter 8...")
- [ ] Future content referenced generically ("covered later", "in future chapter")
- [ ] Placeholders for cross-references clearly marked as [TBD] if necessary
- [ ] Readers know what content is coming vs. what exists now
## Code Repository
- [ ] Chapter code available in GitHub repository
- [ ] Repository link included prominently in chapter
- [ ] Chapter folder clearly labeled (chapter-05, etc.)
- [ ] README in chapter folder explains examples
- [ ] All code for this chapter tested and working
## MEAP-Specific Content
- [ ] MEAP disclaimer/notice included (if required by Manning)
- [ ] "What's coming next" section at end of chapter
- [ ] Preview of future chapters provided
- [ ] Feedback mechanism explained (forum link, etc.)
- [ ] Version/status noted (Draft 1, Draft 2, Final, etc.)
## Author Voice
- [ ] Consistent with other MEAP chapters
- [ ] Professional and engaging tone
- [ ] No abrupt tone changes
- [ ] Personal anecdotes appropriate and relevant
- [ ] Encouraging to early readers
## Content Quality
- [ ] Technical accuracy verified
- [ ] Code examples tested and working
- [ ] Figures and diagrams finalized (or marked as draft)
- [ ] No placeholder text left ([TK], [TODO], etc.)
- [ ] Grammar and spelling checked
## Manning Formatting
- [ ] Follows Manning style guide
- [ ] Headings use correct levels (H1, H2, H3)
- [ ] Code blocks formatted correctly
- [ ] Callouts (Note, Tip, Warning) used appropriately
- [ ] Figure captions formatted correctly
- [ ] Lists formatted consistently
## Educational Value
- [ ] Chapter teaches something valuable on its own
- [ ] Exercises included and solutions provided (appendix or separate)
- [ ] Learning objectives met by end of chapter
- [ ] Progressive complexity (simple to advanced)
- [ ] Examples are realistic and practical
## Reader Engagement
- [ ] Chapter is engaging from the first paragraph
- [ ] No long, dry sections without examples
- [ ] Code examples support the narrative
- [ ] Exercises reinforce learning
- [ ] Reader feels they accomplished something after reading
## Figures and Diagrams
- [ ] All figures numbered correctly (Figure 5.1, 5.2, etc.)
- [ ] Figure captions descriptive
- [ ] Figures referenced in text before they appear
- [ ] Diagrams at acceptable resolution (can be draft quality for early MEAP)
- [ ] Placeholders clearly marked if final diagrams pending
## Cross-References
- [ ] Internal chapter references work (Section 5.3, etc.)
- [ ] References to released chapters are accurate
- [ ] External links tested and working
- [ ] Code repository links functional
## Length and Scope
- [ ] Chapter length appropriate (not too short or too long)
- [ ] Scope matches chapter title and objectives
- [ ] No scope creep beyond chapter's purpose
- [ ] Pacing is good (not rushed or too slow)
## Feedback Readiness
- [ ] Open to constructive criticism from MEAP readers
- [ ] Plan for incorporating feedback
- [ ] Clear on what can/can't change based on feedback
- [ ] Mechanism for tracking and responding to feedback
## Technical Review
- [ ] Code reviewed by at least one other person
- [ ] Technical reviewer feedback incorporated
- [ ] No known errors or bugs
- [ ] Best practices followed
## MEAP Forum/Community
- [ ] Author prepared to engage with MEAP readers
- [ ] Forum link included in chapter
- [ ] Expectations set for author responsiveness
- [ ] Community guidelines understood
## Version Control
- [ ] Chapter version clearly labeled (Draft 1, v0.1, etc.)
- [ ] Changes from previous MEAP release documented (if update)
- [ ] Original source files backed up
- [ ] Submission package clearly labeled
## Final Checks
- [ ] One final read-through completed
- [ ] Fresh eyes reviewed chapter (colleague, friend)
- [ ] No embarrassing errors or typos in opening paragraphs
- [ ] Chapter starts strong and ends strong
- [ ] Ready for early reader scrutiny
## Post-Release Plan
- [ ] Plan to monitor feedback
- [ ] Timeline for incorporating feedback
- [ ] Process for updating MEAP chapters
- [ ] Communication plan for notifying readers of updates

83
expansion-packs/bmad-technical-writing/checklists/readability-checklist.md Normal file
View File

@ -0,0 +1,83 @@
# Readability Checklist
Use this checklist to ensure writing is clear, concise, and easy to understand.
## Sentence Structure
- [ ] Most sentences under 25 words
- [ ] Active voice preferred over passive ("You can do X" vs "X can be done")
- [ ] One main idea per sentence
- [ ] Vary sentence length for rhythm
- [ ] Avoid run-on sentences
## Paragraph Structure
- [ ] Paragraphs focus on one idea
- [ ] First sentence introduces paragraph topic
- [ ] Paragraphs are 3-7 sentences typically
- [ ] Avoid wall-of-text paragraphs
- [ ] Smooth transitions between paragraphs
## Word Choice
- [ ] Prefer simple words over complex ("use" vs "utilize")
- [ ] Avoid unnecessary jargon
- [ ] Define technical terms before using
- [ ] Consistent terminology throughout
- [ ] Avoid vague words ("stuff", "things", "very")
## Clarity
- [ ] Main point is obvious in each section
- [ ] No ambiguous pronoun references ("it", "this", "that")
- [ ] Acronyms defined on first use
- [ ] Examples support concepts clearly
- [ ] Concrete examples preferred over abstract
## Organization
- [ ] Logical flow from simple to complex
- [ ] Related information grouped together
- [ ] Headings are descriptive and helpful
- [ ] Bulleted lists for multiple items
- [ ] Numbered lists for sequential steps
## Headings
- [ ] Headings describe content accurately
- [ ] Hierarchy is clear (H1, H2, H3)
- [ ] Parallel structure in heading lists
- [ ] Scannable headings aid navigation
- [ ] Avoid overly clever or obscure headings
## Transitions
- [ ] Smooth transitions between sections
- [ ] Connection between chapters clear
- [ ] Signposting guides reader ("First, Next, Finally")
- [ ] Forward and backward references clear
- [ ] Logical progression obvious
## Technical Content
- [ ] Code examples follow explanations
- [ ] Complex code broken into digestible chunks
- [ ] Step-by-step procedures clearly numbered
- [ ] Prerequisites stated upfront
- [ ] Expected outcomes described
## Audience Awareness
- [ ] Appropriate for target skill level
- [ ] Assumes correct baseline knowledge
- [ ] Explains necessary background
- [ ] Doesn't over-explain obvious points
- [ ] Doesn't under-explain complex concepts
## Readability Metrics
- [ ] Flesch Reading Ease score reasonable for technical content (40-60 acceptable)
- [ ] Grade level appropriate for audience
- [ ] Average sentence length reasonable (15-20 words)
- [ ] Passive voice usage minimal (<10%)
- [ ] Adverb usage minimal

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

@ -0,0 +1,141 @@
# Repository Quality Checklist
Use this checklist to ensure your code repository is professional, organized, and user-friendly.
## Repository Basics
- [ ] Clear README.md in root directory
- [ ] Repository name descriptive and professional
- [ ] Description accurate in repository settings
- [ ] Topics/tags added for discoverability
- [ ] Repository is public (unless there's a reason for private)
## README.md Quality
- [ ] Title clearly states repository purpose
- [ ] "About This Repository" section explains context
- [ ] Prerequisites listed explicitly
- [ ] Installation instructions step-by-step
- [ ] Usage examples provided
- [ ] Links to book or related resources
- [ ] Repository structure explained
- [ ] Contact/support information included
## Folder Structure
- [ ] Logical organization (by chapter, topic, or feature)
- [ ] Consistent naming conventions (chapter-01, ch01, or 01-chapter-name)
- [ ] Each chapter/section has its own folder
- [ ] Separate folders for tests, docs, images (if applicable)
- [ ] No cluttered root directory
## Code Quality
- [ ] All code follows language-specific style guide
- [ ] Code is well-commented
- [ ] No commented-out code left in repository
- [ ] No debugging print statements left in code
- [ ] Code examples are self-contained and runnable
- [ ] Each example includes necessary imports/dependencies
## Dependencies
- [ ] Requirements file present (requirements.txt, package.json, Gemfile, etc.)
- [ ] Dependencies pinned to specific versions
- [ ] No unnecessary dependencies
- [ ] Instructions for installing dependencies in README
- [ ] Separate dev dependencies if applicable
## Documentation
- [ ] Each chapter folder has its own README (optional but helpful)
- [ ] Code examples explained in comments or accompanying markdown
- [ ] Expected output documented
- [ ] Common issues/troubleshooting noted
- [ ] API documentation if applicable
## Testing
- [ ] Unit tests included (if appropriate)
- [ ] Test instructions in README
- [ ] Tests pass before committing
- [ ] CI/CD set up to run tests automatically (optional)
- [ ] Test coverage reasonable for educational repository
## Git Hygiene
- [ ] .gitignore appropriate for language/framework
- [ ] No sensitive data committed (API keys, passwords, credentials)
- [ ] No large binary files (unless necessary)
- [ ] No IDE-specific files (.vscode/, .idea/ ignored)
- [ ] No OS-specific files (.DS_Store, Thumbs.db ignored)
- [ ] Commit messages are descriptive
- [ ] No merge conflict markers in code
## Licensing
- [ ] LICENSE file present
- [ ] License appropriate for educational code (MIT, Apache 2.0 common)
- [ ] License year and copyright holder correct
- [ ] License compatible with book's license
## Cross-Platform Support
- [ ] Code works on Windows, macOS, Linux (as applicable)
- [ ] File paths use cross-platform methods
- [ ] Installation instructions for all platforms
- [ ] Platform-specific issues documented
## Accessibility
- [ ] Code examples run out-of-the-box (no complex setup)
- [ ] Error messages are helpful
- [ ] Installation doesn't require expensive tools
- [ ] Alternative approaches provided if dependencies are heavy
## GitHub/GitLab Features
- [ ] Repository topics/tags set
- [ ] Issues enabled (if accepting feedback)
- [ ] Discussions enabled (if building community)
- [ ] Security policy (SECURITY.md) if applicable
- [ ] Contributing guidelines (CONTRIBUTING.md) if accepting PRs
## CI/CD (Optional but Recommended)
- [ ] GitHub Actions or equivalent set up
- [ ] Tests run automatically on push/PR
- [ ] Linting checks automated
- [ ] Build status badge in README
- [ ] Multi-platform testing (if applicable)
## Release Management
- [ ] Tagged releases for book versions (v1.0, v2.0, etc.)
- [ ] Release notes describing changes
- [ ] Stable branch for published version
- [ ] Development branch for updates (if applicable)
## Reader Experience
- [ ] Clone and run test: can a reader clone and run immediately?
- [ ] Instructions are clear to someone unfamiliar with the repository
- [ ] No "works on my machine" problems
- [ ] Examples produce expected output
- [ ] Repository organized logically from reader's perspective
## Maintenance
- [ ] Dependencies not outdated (security vulnerabilities)
- [ ] Deprecated features noted
- [ ] Updates planned for major language/framework changes
- [ ] Errata or known issues documented
- [ ] Responsive to issues and questions (if accepting them)
## Integration with Book
- [ ] Repository linked prominently in book's front matter
- [ ] Repository URL easy to type (short, memorable)
- [ ] Chapter code maps clearly to book chapters
- [ ] Repository supports book's learning objectives
- [ ] Code in repository matches code in book (or noted if intentionally different)

152
expansion-packs/bmad-technical-writing/checklists/self-publishing-standards-checklist.md Normal file
View File

@ -0,0 +1,152 @@
# Self-Publishing Standards Checklist
Use this checklist to ensure your self-published book meets professional quality standards.
## Cover Design
- [ ] Professional cover design (not DIY unless experienced)
- [ ] Title readable at thumbnail size
- [ ] High resolution (2560 x 1600 px minimum for KDP)
- [ ] Front, back, and spine designed (for print)
- [ ] Cover conveys book topic clearly
- [ ] Cover design appropriate for genre/topic
- [ ] ISBN and barcode included (for print)
## Formatting - eBook
- [ ] Clean HTML/ePub formatting
- [ ] Table of contents with working links
- [ ] No formatting errors (extra spaces, missing paragraphs, etc.)
- [ ] Images sized appropriately for e-readers
- [ ] Code blocks formatted and readable
- [ ] Tested on Kindle (Fire, Paperwhite, app)
- [ ] Tested on Kobo/Nook (if distributing there)
- [ ] Tested on iPad/iPhone Books app
- [ ] Font choices appropriate (or use device defaults)
## Formatting - Print (if applicable)
- [ ] Proper page size selected (6x9, 7x10, 8.5x11, etc.)
- [ ] Margins appropriate for binding
- [ ] Headers/footers professional
- [ ] Page numbers correct
- [ ] Chapter starts formatted consistently
- [ ] No orphans/widows (single lines at top/bottom of page)
- [ ] Images high resolution (300 DPI minimum)
- [ ] Bleed settings correct (if using bleed)
## Front Matter
- [ ] Title page
- [ ] Copyright page with correct year and copyright notice
- [ ] ISBN on copyright page (if using)
- [ ] Edition statement (if applicable)
- [ ] Disclaimers (if applicable)
- [ ] Table of contents
- [ ] Preface or introduction (optional but recommended)
## Back Matter
- [ ] About the author
- [ ] Other books by author (if applicable)
- [ ] Thank you / call to action (optional)
- [ ] Contact information or website
- [ ] Request for reviews (optional)
## Metadata - All Platforms
- [ ] Title accurate and searchable
- [ ] Subtitle descriptive
- [ ] Author name consistent across platforms
- [ ] Book description compelling (150-300 words)
- [ ] Keywords researched and targeted (up to 7 typically)
- [ ] Categories selected strategically
- [ ] Language set correctly
- [ ] Publication date accurate
## Pricing
- [ ] Price competitive with similar books
- [ ] Royalty tier considered (70% vs 35% on KDP)
- [ ] Print price covers costs + margin
- [ ] Different prices for different markets considered
- [ ] Promotional pricing strategy planned
## Legal Requirements
- [ ] Copyright notice included
- [ ] ISBN obtained (if required/desired)
- [ ] No copyright violations
- [ ] Permissions obtained for quoted material
- [ ] Disclaimers appropriate for content
## Quality Control
- [ ] Professional editing completed (developmental, copy, proofread)
- [ ] Beta readers provided feedback
- [ ] Errors corrected from beta feedback
- [ ] Final proofread by fresh eyes
- [ ] All links tested (URLs, email, cross-references)
## Preview and Samples
- [ ] "Look Inside" / preview set up (first 10% typically)
- [ ] Preview represents book well
- [ ] No errors in preview section
- [ ] Sample chapters engaging
## Platform-Specific - Leanpub
- [ ] Markdown formatted correctly
- [ ] Book.txt configured with chapter order
- [ ] Subset.txt configured for sample chapters
- [ ] Metadata complete in Book.txt
- [ ] Preview generated and reviewed
- [ ] Pricing set (minimum, suggested, maximum)
## Platform-Specific - Amazon KDP
- [ ] KDP account set up with tax information
- [ ] eBook uploaded and validated
- [ ] Print book uploaded (if applicable) and validated
- [ ] Cover meets KDP requirements
- [ ] ISBN assigned (using free KDP ISBN or own)
- [ ] Preview generated and reviewed
- [ ] Categories selected (up to 2 + keywords)
- [ ] Kindle Unlimited enrollment decision made
## Platform-Specific - Gumroad
- [ ] Product description complete
- [ ] Files uploaded (PDF, ePub, extras)
- [ ] Preview/sample provided
- [ ] Pricing set
- [ ] Payment processing configured
- [ ] Email delivery set up
- [ ] Thank you page configured
## Marketing Preparation
- [ ] Book website or landing page created
- [ ] Social media announcements prepared
- [ ] Email list notified (if applicable)
- [ ] Launch plan in place
- [ ] Review copy strategy (ARC readers, influencers)
- [ ] Promotional materials ready (graphics, snippets, quotes)
## Post-Launch
- [ ] Monitor for errors or reader feedback
- [ ] Plan for updates/revisions
- [ ] Errata page prepared (if needed)
- [ ] Review requests sent to readers
- [ ] Respond to reader questions/feedback
- [ ] Track sales and adjust marketing
## Professional Standards
- [ ] Book indistinguishable from traditionally published books
- [ ] No obvious self-publishing markers (unless intentional)
- [ ] Quality equals or exceeds competing books
- [ ] Reader experience prioritized
- [ ] Ongoing improvement mindset (update based on feedback)

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

@ -1,22 +1,31 @@
# <!-- Powered by BMAD™ Core -->
name: bmad-technical-writing
version: 1.0.0
version: 1.1.0
short-title: Technical Book Writing Studio
description: >-
Production-ready AI-powered technical writing framework for technical book
authors, technical trainers, and documentation specialists. Provides 10
specialized agents (9 greenfield + 1 brownfield), 12 workflows (9 greenfield + 3 brownfield),
and professional quality assurance tools for planning, writing, revising,
reviewing, and publishing technical books with code examples, tutorials, and
learning objectives. Includes 21 checklists for technical accuracy, security,
authors, technical trainers, and documentation specialists. Provides 13
specialized agents (10 required + 3 optional), 15 workflows, and comprehensive
quality assurance tools for planning, writing, revising, reviewing, and
publishing technical books with code examples, tutorials, and learning
objectives. Includes 31 checklists for technical accuracy, security,
performance, publisher compliance, accessibility, visual quality, documentation,
and brownfield integration. 15 professional templates cover book planning,
chapter development, API reference, diagrams, publishing, book analysis, and
revision planning. Section-driven workflows enable incremental chapter
development (2-5 pages per section) with parallel development capabilities.
Brownfield support enables 2nd/3rd edition updates, technology version migrations,
chapter additions to existing books, and systematic reviewer feedback incorporation.
Supports publishers like PacktPub, O'Reilly, Manning, and self-publishing
platforms (Leanpub/KDP/Gumroad).
cross-platform compatibility, inclusive language, readability, indexing,
citations, final manuscript review, book proposals, self-publishing standards,
repository quality, and MEAP readiness. 18 professional templates cover book
planning, chapter development, API reference, diagrams, publishing, book
analysis, revision planning, and glossary entries. 33 tasks handle all
authoring workflows from learning path design to version matrix testing,
code repository setup, solutions creation, index generation, screenshot
management, publisher packaging, MEAP preparation, self-publishing prep,
preface/appendix creation, diagram set design, and cross-reference validation.
Section-driven workflows enable incremental chapter development (2-5 pages per
section) with parallel development capabilities. Brownfield support enables
2nd/3rd edition updates, technology version migrations, chapter additions to
existing books, and systematic reviewer feedback incorporation. Optional agents
(Learning Path Designer, Sample Code Maintainer, Version Manager) enhance
advanced scenarios without complexity overhead. Achieves 100% coverage of
research specifications. Supports publishers like PacktPub, O'Reilly, Manning,
and self-publishing platforms (Leanpub/KDP/Gumroad).
author: Wes
slashPrefix: bmad-tw

213
expansion-packs/bmad-technical-writing/tasks/create-appendix.md Normal file
View File

@ -0,0 +1,213 @@
<!-- Powered by BMAD™ Core -->
# Create Appendix
---
task:
id: create-appendix
name: Create Appendix
description: Develop comprehensive appendix content including reference materials, installation guides, and troubleshooting
persona_default: technical-editor
inputs:
- appendix-type
- content-requirements
- book-chapters
steps:
- Identify appendix content (reference tables, installation guides, troubleshooting)
- Organize by topic
- Create clear appendix titles
- Reference from main chapters
- Include platform-specific installation guides
- Add troubleshooting FAQ
- List additional resources (links, books, websites)
- Ensure consistent formatting
- Add to table of contents
- Index appendix content
- Use template appendix-tmpl.yaml with create-doc.md
output: back-matter/appendix-{{letter}}.md
---
## Purpose
Create valuable reference appendices that complement the main text and help readers solve common problems.
## Workflow Steps
### 1. Identify Appendix Content
**Common Appendix Types:**
- **Appendix A**: Exercise solutions
- **Appendix B**: Reference tables (HTTP codes, SQL commands, etc.)
- **Appendix C**: Installation and setup guides
- **Appendix D**: Troubleshooting and FAQs
- **Appendix E**: Additional resources
- **Appendix F**: Glossary of terms
### 2. Organize by Topic
Structure clearly:
```markdown
# Appendix A: Exercise Solutions
## Chapter 1 Solutions
### Exercise 1.1
[Solution]
### Exercise 1.2
[Solution]
## Chapter 2 Solutions
[...]
```
### 3. Reference from Chapters
Cross-reference effectively:
```markdown
For complete HTTP status code reference, see Appendix B.
Try the exercises at the end of this chapter (solutions in Appendix A).
Installation instructions for all platforms are in Appendix C.
```
### 4. Platform-Specific Installation
Cover all platforms:
```markdown
# Appendix C: Installation Guide
## Installing Python
### Windows
1. Download Python 3.11+ from python.org
2. Run installer, check "Add Python to PATH"
3. Verify: Open PowerShell and run `python --version`
### macOS
1. Install Homebrew: `/bin/bash -c "$(curl -fsSL...)"`
2. Install Python: `brew install python@3.11`
3. Verify: `python3 --version`
### Linux (Ubuntu/Debian)
```bash
sudo apt update
sudo apt install python3.11
python3.11 --version
```
```
### 5. Troubleshooting FAQ
Common issues:
```markdown
# Appendix D: Troubleshooting
## Python Issues
### Q: "python: command not found"
**Problem**: Python not in PATH
**Solution (Windows)**: Reinstall Python, check "Add to PATH" option
**Solution (Mac/Linux)**: Use `python3` instead of `python`
### Q: "ModuleNotFoundError: No module named 'requests'"
**Problem**: Package not installed
**Solution**: `pip install requests`
## API Issues
### Q: 401 Unauthorized errors
**Causes**:
- Expired JWT token
- Missing Authorization header
- Invalid API key
**Solutions**:
- Refresh token
- Add header: `Authorization: Bearer [token]`
- Verify API key in environment variables
```
### 6. Additional Resources
Curated links:
```markdown
# Appendix E: Additional Resources
## Official Documentation
- Python Requests Library: https://requests.readthedocs.io
- Flask Documentation: https://flask.palletsprojects.com
- FastAPI: https://fastapi.tiangolo.com
## Books
- "RESTful Web APIs" by Leonard Richardson & Mike Amundsen
- "Designing Data-Intensive Applications" by Martin Kleppmann
## Online Resources
- REST API Tutorial: https://restfulapi.net
- HTTP Cats (status codes): https://http.cat
- JSON Placeholder (test API): https://jsonplaceholder.typicode.com
## Tools
- Postman (API testing)
- Insomnia (API client)
- HTTPie (command-line HTTP client)
```
### 7. Reference Tables
Quick lookup:
```markdown
# Appendix B: HTTP Status Code Reference
| Code | Name | Meaning |
|------|------|---------|
| 200 | OK | Request succeeded |
| 201 | Created | Resource created successfully |
| 204 | No Content | Success but no content to return |
| 400 | Bad Request | Invalid request syntax |
| 401 | Unauthorized | Authentication required |
| 403 | Forbidden | Authenticated but not authorized |
| 404 | Not Found | Resource doesn't exist |
| 500 | Internal Server Error | Server-side error |
| 503 | Service Unavailable | Server temporarily unavailable |
```
### 8. Index Appendix Content
Ensure discoverability:
```markdown
\index{HTTP status codes}
\index{Installation!Python}
\index{Troubleshooting}
```
## Success Criteria
- [ ] Appendix content identified
- [ ] Organized logically by topic
- [ ] Clear titles for each appendix
- [ ] Referenced from main chapters
- [ ] Platform-specific guides included
- [ ] Troubleshooting FAQ comprehensive
- [ ] Additional resources curated
- [ ] Consistent formatting
- [ ] Added to table of contents
- [ ] Content indexed
## Next Steps
1. Add appendices to back matter
2. Cross-reference from chapters
3. Update during technical review

157
expansion-packs/bmad-technical-writing/tasks/create-index-entries.md Normal file
View File

@ -0,0 +1,157 @@
<!-- Powered by BMAD™ Core -->
# Create Index Entries
---
task:
id: create-index-entries
name: Create Index Entries
description: Generate comprehensive book index with primary entries, secondary entries, and cross-references
persona_default: technical-editor
inputs:
- final-manuscript
- key-terms-list
- publisher-index-guidelines
steps:
- Extract all key terms from manuscript
- Identify technical terms, concepts, APIs, methods
- Create primary index entries (main term)
- Create secondary entries (sub-topics under main term)
- Add cross-references ("See also...")
- Ensure consistent terminology
- Organize alphabetically
- Add page number placeholders
- Review for completeness (all important terms indexed)
- Format per publisher requirements
- Run execute-checklist.md with index-completeness-checklist.md
output: docs/index/{{book-name}}-index.md
---
## Purpose
Create a comprehensive index that helps readers quickly locate information. A good index makes technical books significantly more useful as reference materials.
## Workflow Steps
### 1. Extract Key Terms
Identify indexable content:
- **Technical terms**: API, HTTP, REST, JSON
- **Concepts**: Authentication, caching, rate limiting
- **Tools/frameworks**: Express.js, Flask, Django
- **Methods/functions**: `app.get()`, `request.json()`
- **Patterns**: MVC, Singleton, Factory
- **Acronyms**: CRUD, JWT, CORS
### 2. Create Primary Entries
Main index entries:
```
API (Application Programming Interface), 23, 45-52, 89
authentication, 105-112
design principles, 67-74
documentation, 156-163
REST vs GraphQL, 91-98
versioning, 142-149
Caching, 201-218
cache invalidation, 210-212
HTTP caching headers, 205-209
Redis implementation, 213-218
```
### 3. Add Secondary Entries
Sub-topics under main terms:
```
Express.js, 34-82
error handling, 76-82
middleware, 48-55
routing, 38-47
testing, 171-180
```
### 4. Cross-References
Link related topics:
```
Authentication, 105-112
See also Security, Authorization
JWT (JSON Web Tokens), 108-110
See also Authentication, Tokens
Tokens
access tokens, 110
refresh tokens, 111
See also JWT, Authentication
```
### 5. Ensure Consistency
Maintain uniform terminology:
```
✅ Correct - Consistent terminology:
API design, 67
REST API, 91
API authentication, 105
❌ Inconsistent:
API design, 67
Designing APIs, 67 (duplicate)
Rest api, 91 (capitalization inconsistent)
```
### 6. Format Per Publisher
Follow publisher guidelines:
**Manning/O'Reilly Style:**
```
Term, page numbers
subterm, page numbers
subterm, page numbers
```
**LaTeX Style:**
```
\index{API}
\index{API!authentication}
\index{API!design}
```
### 7. Add Page Placeholders
Structure for page numbering:
```
API (Application Programming Interface), [TK], [TK]-[TK]
authentication, [TK]-[TK]
design principles, [TK]-[TK]
Note: [TK] = "To Come" placeholder for page numbers
```
## Success Criteria
- [ ] All key terms indexed
- [ ] Primary and secondary entries created
- [ ] Cross-references added
- [ ] Consistent terminology
- [ ] Alphabetically organized
- [ ] Publisher format followed
- [ ] Index completeness checklist passed
## Next Steps
1. Submit index to publisher for page numbering
2. Review final index in page proofs
3. Update any missing entries

253
expansion-packs/bmad-technical-writing/tasks/create-preface.md Normal file
View File

@ -0,0 +1,253 @@
<!-- Powered by BMAD™ Core -->
# Create Preface
---
task:
id: create-preface
name: Create Preface
description: Write compelling book preface that sets expectations and connects with readers
persona_default: book-analyst
inputs:
- book-outline
- target-audience
- learning-objectives
steps:
- Review preface template
- Define target audience clearly
- Explain what readers will learn (high-level outcomes)
- State prerequisites assumed
- Describe book organization (parts, structure)
- List code repository and resources
- Explain conventions used (code formatting, callouts)
- Write acknowledgments
- Add personal note if desired
- Keep concise (2-4 pages max)
- Use template preface-tmpl.yaml with create-doc.md
output: front-matter/preface.md
---
## Purpose
Create a preface that helps readers understand who the book is for, what they'll learn, and how to use it effectively.
## Workflow Steps
### 1. Define Target Audience
Be specific:
```markdown
## Who This Book Is For
This book is designed for:
✅ **Software developers** with 1-2 years of experience who want to master API development
✅ **Backend engineers** transitioning to API-first architectures
✅ **Full-stack developers** looking to strengthen their API design skills
You'll get the most from this book if you have:
- Working knowledge of Python or JavaScript
- Basic understanding of HTTP and web concepts
- Familiarity with command line tools
This book may not be for you if:
❌ You're brand new to programming (start with Python/JavaScript fundamentals)
❌ You're looking for advanced distributed systems architecture (this focuses on API basics and intermediate patterns)
```
### 2. Explain Learning Outcomes
High-level goals:
```markdown
## What You'll Learn
By the end of this book, you'll be able to:
1. **Design RESTful APIs** that follow industry best practices
2. **Implement authentication** using JWT and OAuth 2.0
3. **Build GraphQL schemas** and resolvers
4. **Handle errors gracefully** with consistent error responses
5. **Optimize API performance** with caching and rate limiting
6. **Deploy APIs to production** on AWS, Heroku, or Docker
7. **Document APIs** using OpenAPI/Swagger
You'll build real-world projects including:
- Task management API (REST)
- E-commerce backend (GraphQL)
- Real-time chat API (WebSockets)
```
### 3. State Prerequisites
Be honest about assumptions:
```markdown
## Prerequisites
**Required:**
- Python 3.10+ or Node.js 18+ installed
- Basic HTTP knowledge (GET, POST, status codes)
- Comfortable with command line
- Text editor or IDE
**Helpful but not required:**
- SQL database experience
- Git version control
- Basic Docker knowledge
```
### 4. Describe Book Organization
Help readers navigate:
```markdown
## How This Book Is Organized
This book is organized into three parts:
**Part 1: Foundations (Chapters 1-4)**
Covers REST fundamentals, HTTP, and basic API design. Read these chapters in order.
**Part 2: Intermediate Patterns (Chapters 5-8)**
Authentication, error handling, testing, and documentation. Mostly independent chapters.
**Part 3: Production Readiness (Chapters 9-12)**
Performance, security, deployment, and monitoring. Builds on earlier chapters.
**Appendices:**
- A: API design checklist
- B: HTTP status codes reference
- C: Exercise solutions
### Reading Paths
**Linear (Recommended for Beginners):**
Read chapters 1-12 in order.
**Fast Track (Experienced Developers):**
Chapters 1, 3, 5, 7, 9-12 (skip basics).
**Reference Use:**
Jump to specific topics as needed; each chapter is as self-contained as possible.
```
### 5. List Resources
Make code accessible:
```markdown
## Code and Resources
### Code Repository
All code examples: https://github.com/author/book-code
### Book Website
https://masteringwebapis.com
- Errata and updates
- Additional resources
- Community forum
### Author Contact
- Twitter: @authorhandle
- Email: author@example.com
- Newsletter: [signup link]
```
### 6. Explain Conventions
Set expectations:
```markdown
## Conventions Used in This Book
### Code Examples
```python
# Code examples look like this
def hello_world():
return "Hello, World!"
```
### Callouts
💡 **Tip**: Helpful suggestions and best practices
⚠️ **Warning**: Common pitfalls to avoid
📝 **Note**: Additional context or clarification
### Chapter Structure
Each chapter includes:
- Learning objectives
- Code examples with explanations
- Exercises (solutions in Appendix C)
- Summary and key takeaways
```
### 7. Write Acknowledgments
Thank contributors:
```markdown
## Acknowledgments
This book wouldn't exist without:
- **Technical reviewers**: [Names] who caught errors and improved clarity
- **Manning staff**: [Editor names] for guidance and support
- **Beta readers**: The MEAP community for invaluable feedback
- **My family**: [Personal thanks]
- **Open source community**: For the amazing tools and libraries
Special thanks to [specific acknowledgments].
```
### 8. Add Personal Note
Connect with readers:
```markdown
## A Note from the Author
I started learning about APIs five years ago, frustrated by incomplete documentation
and scattered resources. This book is what I wish I had back then: a comprehensive,
practical guide with working examples.
My goal is not just to teach you API syntax, but to help you think like an API designer.
Every example is tested, every pattern is battle-proven, and every chapter builds toward
real-world competence.
I hope this book accelerates your journey and helps you build APIs that developers love to use.
Happy coding!
[Author Name]
```
### 9. Keep Concise
Target length: 2-4 pages (1000-2000 words)
## Success Criteria
- [ ] Target audience clearly defined
- [ ] Learning outcomes specific and achievable
- [ ] Prerequisites stated honestly
- [ ] Book organization explained
- [ ] Code repository and resources listed
- [ ] Conventions documented
- [ ] Acknowledgments included
- [ ] Length: 2-4 pages
- [ ] Personal and engaging tone
## Next Steps
1. Include preface in front matter
2. Update as book evolves
3. Get feedback from beta readers

341
expansion-packs/bmad-technical-writing/tasks/create-solutions.md Normal file
View File

@ -0,0 +1,341 @@
<!-- Powered by BMAD™ Core -->
# Create Solutions
---
task:
id: create-solutions
name: Create Solutions
description: Develop complete, tested solutions for all exercises with multiple approaches and explanations
persona_default: exercise-creator
inputs:
- chapter-exercises
- difficulty-level
- target-audience
steps:
- Review all exercises in chapter
- Write complete tested solutions for each
- Include multiple solution approaches where applicable
- Add explanatory comments in solution code
- Document solution reasoning (why this approach)
- Test solutions thoroughly
- Create solution variations (beginner vs advanced)
- Add common mistake examples
- Estimate time to complete each exercise
- Format solutions for appendix or separate file
- Run execute-checklist.md with exercise-difficulty-checklist.md
output: docs/solutions/chapter-{{n}}-solutions.md
---
## Purpose
This task guides you through creating comprehensive, educational solutions for all chapter exercises. Good solutions teach readers how to approach problems, not just provide answers.
## Workflow Steps
### 1. Review All Exercises
Catalog chapter exercises:
- List each exercise with its learning objective
- Note difficulty level (beginner/intermediate/advanced)
- Identify which concepts each exercise reinforces
- Check that exercises align with chapter content
### 2. Write Complete, Tested Solutions
Develop working solutions:
**Solution Requirements:**
- Code executes successfully
- Produces expected output
- Follows best practices from chapter
- Includes all necessary imports/setup
- Handles edge cases appropriately
**Example Solution:**
```python
# Exercise 3.2: Implement a function to validate email addresses
import re
def validate_email(email):
"""
Validate email address format.
Args:
email (str): Email address to validate
Returns:
bool: True if valid, False otherwise
"""
# Pattern explanation:
# - ^[a-zA-Z0-9._%+-]+ : Username part (letters, numbers, special chars)
# - @ : Required @ symbol
# - [a-zA-Z0-9.-]+ : Domain name
# - \.[a-zA-Z]{2,}$ : Top-level domain (minimum 2 chars)
pattern = r'^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$'
return bool(re.match(pattern, email))
# Test cases
assert validate_email("user@example.com") == True
assert validate_email("invalid.email") == False
assert validate_email("user@domain.co.uk") == True
```
### 3. Include Multiple Approaches
Show alternative solutions:
**Example - Multiple Approaches:**
```python
# Approach 1: Using regular expressions (recommended)
def validate_email_regex(email):
pattern = r'^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$'
return bool(re.match(pattern, email))
# Approach 2: Using string methods (simpler but less robust)
def validate_email_simple(email):
return '@' in email and '.' in email.split('@')[-1]
# Approach 3: Using email library (most robust)
from email_validator import validate_email, EmailNotValidError
def validate_email_robust(email):
try:
validate_email(email)
return True
except EmailNotValidError:
return False
# Trade-offs:
# - Approach 1: Good balance of simplicity and accuracy
# - Approach 2: Too simple, accepts invalid emails
# - Approach 3: Most accurate, requires external library
```
### 4. Add Explanatory Comments
Explain the reasoning:
```python
def fibonacci(n):
"""Generate Fibonacci sequence up to n terms."""
# We use an iterative approach rather than recursion
# because it's more efficient (O(n) vs O(2^n) time complexity)
# and avoids stack overflow for large n
if n <= 0:
return []
elif n == 1:
return [0]
# Initialize first two Fibonacci numbers
sequence = [0, 1]
# Generate remaining terms
# Each term is the sum of the previous two
for i in range(2, n):
next_term = sequence[i-1] + sequence[i-2]
sequence.append(next_term)
return sequence
```
### 5. Document Solution Reasoning
Explain why this approach:
**Reasoning Template:**
```markdown
## Exercise 3.4 Solution
### Chosen Approach: Iterative Implementation
**Why this approach?**
- Time complexity: O(n) - efficient for large inputs
- Space complexity: O(n) - stores full sequence
- Avoids recursion depth limits
- Easy to understand and debug
**Alternative approaches considered:**
- Recursive: Simpler code but O(2^n) time complexity
- Generator: More memory-efficient but doesn't return list
- Matrix multiplication: Mathematically elegant but overkill
**When to use each:**
- Use iterative for most cases (good balance)
- Use generator when working with very large n
- Use recursive for teaching purposes only
```
### 6. Test Solutions Thoroughly
Validate correctness:
```python
# Comprehensive test suite for solution
def test_fibonacci():
# Test edge cases
assert fibonacci(0) == []
assert fibonacci(1) == [0]
assert fibonacci(2) == [0, 1]
# Test normal cases
assert fibonacci(5) == [0, 1, 1, 2, 3]
assert fibonacci(10) == [0, 1, 1, 2, 3, 5, 8, 13, 21, 34]
# Test correctness of sequence
result = fibonacci(20)
for i in range(2, len(result)):
assert result[i] == result[i-1] + result[i-2]
```
### 7. Create Solution Variations
Provide beginner and advanced versions:
**Beginner Solution (verbose, educational):**
```python
def calculate_average(numbers):
"""Calculate the average of a list of numbers."""
# First, check if the list is empty to avoid division by zero
if len(numbers) == 0:
return 0
# Initialize a variable to store the sum
total = 0
# Add each number to the total
for number in numbers:
total = total + number
# Divide total by count to get average
count = len(numbers)
average = total / count
return average
```
**Advanced Solution (concise, Pythonic):**
```python
def calculate_average(numbers):
"""Calculate the average of a list of numbers."""
return sum(numbers) / len(numbers) if numbers else 0
```
### 8. Add Common Mistakes
Show what to avoid:
```markdown
## Common Mistakes
### ❌ Mistake 1: Not handling empty input
```python
def calculate_average(numbers):
return sum(numbers) / len(numbers) # ZeroDivisionError if empty!
```
**Problem:** Crashes on empty list.
**Fix:** Check for empty input first.
### ❌ Mistake 2: Modifying input during iteration
```python
def remove_negatives(numbers):
for num in numbers:
if num < 0:
numbers.remove(num) # Skips elements!
return numbers
```
**Problem:** Modifying list while iterating causes skipped elements.
**Fix:** Create new list or iterate backwards.
```
### 9. Estimate Completion Time
Help readers pace themselves:
```markdown
## Exercise Time Estimates
| Exercise | Difficulty | Estimated Time |
|----------|-----------|----------------|
| 3.1 | Beginner | 10-15 minutes |
| 3.2 | Intermediate | 20-30 minutes |
| 3.3 | Advanced | 45-60 minutes |
| 3.4 | Challenge | 1-2 hours |
```
### 10. Format for Appendix
Structure solutions document:
**Template:**
```markdown
# Chapter 3 Solutions
## Exercise 3.1: [Exercise Title]
**Difficulty:** Beginner
**Estimated Time:** 10-15 minutes
### Solution
```python
[solution code]
```
### Explanation
[Detailed explanation of approach]
### Alternative Approaches
[Other valid solutions]
### Common Mistakes
[What to avoid]
---
## Exercise 3.2: [Next Exercise]
[Same structure]
```
## Success Criteria
- [ ] All exercises have complete solutions
- [ ] Solutions are tested and work correctly
- [ ] Multiple approaches shown where applicable
- [ ] Explanatory comments included
- [ ] Solution reasoning documented
- [ ] Beginner and advanced variations provided
- [ ] Common mistakes identified
- [ ] Time estimates provided
- [ ] Formatted for appendix or separate file
- [ ] Exercise difficulty checklist passed
## Next Steps
1. Include solutions in book appendix or companion website
2. Consider providing partial solutions for harder exercises
3. Create solution videos for complex exercises (optional)
4. Test solutions with beta readers

211
expansion-packs/bmad-technical-writing/tasks/design-diagram-set.md Normal file
View File

@ -0,0 +1,211 @@
<!-- Powered by BMAD™ Core -->
# Design Diagram Set
---
task:
id: design-diagram-set
name: Design Diagram Set
description: Plan comprehensive set of diagrams for a chapter with consistent visual style
persona_default: tutorial-architect
inputs:
- chapter-number
- chapter-content
- concepts-to-visualize
steps:
- Review chapter concepts needing visualization
- Identify diagram types needed (architecture, flow, sequence, class, ER)
- Create diagram spec for each using create-diagram-spec task
- Determine common visual style (colors, fonts, shapes)
- Plan diagram progression (simple → complex)
- Ensure diagrams support text not replace it
- Write alternative text for accessibility
- Plan for diagram updates (editable source files)
- Run execute-checklist.md with diagram-clarity-checklist.md
- Run execute-checklist.md with accessibility-checklist.md
- Create implementation plan
output: docs/diagrams/chapter-{{n}}-diagram-plan.md
---
## Purpose
Design a cohesive set of diagrams that enhance chapter understanding through consistent visual communication.
## Workflow Steps
### 1. Review Concepts Needing Visualization
Identify what to diagram:
**Good candidates for diagrams:**
- System architecture
- Data flow
- Process workflows
- Class relationships
- Database schemas
- API request/response cycles
- Component interactions
**Poor candidates:**
- Simple lists (use bullets)
- Linear sequences (use numbered steps)
- Obvious concepts (text is clearer)
### 2. Identify Diagram Types
**Common Technical Diagram Types:**
- **Architecture diagrams**: System components and relationships
- **Flowcharts**: Decision trees and process flows
- **Sequence diagrams**: Interaction over time
- **Class diagrams**: Object-oriented relationships
- **ER diagrams**: Database entity relationships
- **State diagrams**: State transitions
- **Network diagrams**: Infrastructure and connections
### 3. Determine Visual Style
**Consistency elements:**
```yaml
Visual Style Guide:
Colors:
primary: "#2563EB" (blue)
secondary: "#10B981" (green)
warning: "#F59E0B" (orange)
error: "#EF4444" (red)
neutral: "#6B7280" (gray)
Fonts:
headings: "Inter, sans-serif"
labels: "Inter, sans-serif"
code: "JetBrains Mono, monospace"
Shapes:
services: Rounded rectangles
databases: Cylinders
users: Stick figures/icons
external-systems: Dashed borders
Arrows:
data-flow: Solid lines
optional-flow: Dashed lines
bidirectional: Double-headed arrows
```
### 4. Plan Diagram Progression
Build complexity incrementally:
**Example progression for API chapter:**
```markdown
1. Figure 3.1: Simple HTTP request/response (2 boxes)
2. Figure 3.2: Client-Server architecture (4 components)
3. Figure 3.3: Multi-tier architecture with database (6 components)
4. Figure 3.4: Complete system with caching and load balancer (10+ components)
```
### 5. Ensure Diagrams Support Text
Diagrams complement, not replace:
```markdown
✅ Good integration:
"The client sends a request to the API server (Figure 3.1), which queries the
database before returning a response. This request-response cycle..."
❌ Poor integration:
"See Figure 3.1." [end of explanation]
```
### 6. Write Alternative Text
Accessibility requirement:
```markdown
![Alternative text: Sequence diagram showing client sending HTTP GET request
to API server, server querying database, database returning data, and server
sending JSON response back to client]
```
### 7. Plan for Updates
Use editable sources:
**Recommended tools:**
- draw.io (free, open format)
- Lucidchart (professional)
- PlantUML (code-based, version-controllable)
- Mermaid (markdown-based)
**Save source files:**
```
diagrams/
├── sources/
│ ├── chapter-03-architecture.drawio
│ ├── chapter-03-sequence.puml
│ └── chapter-03-er-diagram.drawio
└── exports/
├── chapter-03-architecture.png
├── chapter-03-sequence.png
└── chapter-03-er-diagram.png
```
### 8. Create Implementation Plan
**Diagram Set Plan Template:**
```markdown
# Chapter 3 Diagram Plan
## Diagram 3.1: Simple Request-Response
- **Type**: Sequence diagram
- **Purpose**: Introduce HTTP basics
- **Complexity**: Simple (2 actors)
- **Tool**: PlantUML
- **Alt text**: "HTTP request-response between client and server"
## Diagram 3.2: API Architecture
- **Type**: Architecture diagram
- **Purpose**: Show system components
- **Complexity**: Intermediate (5 components)
- **Tool**: draw.io
- **Alt text**: "Three-tier architecture with client, API server, and database"
## Diagram 3.3: Authentication Flow
- **Type**: Flowchart
- **Purpose**: Illustrate JWT authentication
- **Complexity**: Advanced (decision points, multiple paths)
- **Tool**: Lucidchart
- **Alt text**: "Flowchart showing login, token generation, and API access"
## Visual Consistency
- All diagrams use same color scheme
- Same font (Inter) for labels
- Consistent icon style
- 300 DPI export resolution
```
## Success Criteria
- [ ] Concepts needing visualization identified
- [ ] Diagram types selected appropriately
- [ ] Diagram specs created for each
- [ ] Visual style guide defined
- [ ] Progression from simple to complex
- [ ] Diagrams complement text
- [ ] Alternative text written
- [ ] Editable source files planned
- [ ] Diagram clarity checklist passed
- [ ] Accessibility checklist passed
## Next Steps
1. Create individual diagrams using create-diagram-spec task
2. Review diagrams with technical reviewer
3. Export at required resolution
4. Integrate into chapter

335
expansion-packs/bmad-technical-writing/tasks/design-learning-path.md Normal file
View File

@ -0,0 +1,335 @@
<!-- Powered by BMAD™ Core -->
# Design Learning Path
---
task:
id: design-learning-path
name: Design Learning Path
description: Map prerequisite dependencies and design skill progression for optimal learning flow
persona_default: learning-path-designer
inputs:
- book-outline
- chapter-topics
- target-audience
steps:
- Review book outline and chapter topics
- Identify foundational vs. advanced topics
- Map prerequisite dependencies between chapters
- Design skill scaffolding (simple → complex progression)
- Validate no knowledge gaps in progression
- Assess reader readiness at each chapter
- Identify optional vs. required chapters
- Create dependency diagram
- Verify alignment with learning objectives
- Document learning path in book outline
- Run execute-checklist.md with learning-objectives-checklist.md
- Run execute-checklist.md with prerequisite-clarity-checklist.md
output: docs/learning-path/{{book-name}}-learning-path.md
---
## Purpose
This task guides you through designing a coherent learning progression that scaffolds reader knowledge from foundational concepts to advanced topics. A well-designed learning path ensures readers can successfully navigate the book without encountering unexplained prerequisites or knowledge gaps.
## Prerequisites
Before starting this task:
- Completed book outline with chapter topics
- Clear understanding of target audience skill level
- Access to learning-frameworks.md knowledge base
- Learning objectives defined for each chapter
## Workflow Steps
### 1. Review Book Outline and Chapter Topics
Analyze your book structure:
- List all chapters and their main topics
- Identify the core concepts in each chapter
- Note any technical skills required
- Review the chapter ordering
**Output:** Complete inventory of topics and skills covered
### 2. Identify Foundational vs. Advanced Topics
Categorize content by complexity:
- **Foundational topics**: Required basic knowledge (e.g., "What is an API?")
- **Intermediate topics**: Build on foundations (e.g., "RESTful API design")
- **Advanced topics**: Complex applications (e.g., "API rate limiting strategies")
**Example Categorization:**
```
Foundational:
- Chapter 1: Introduction to Web Development
- Chapter 2: HTML/CSS Basics
- Chapter 3: JavaScript Fundamentals
Intermediate:
- Chapter 4: DOM Manipulation
- Chapter 5: Async Programming
- Chapter 6: HTTP and APIs
Advanced:
- Chapter 7: State Management
- Chapter 8: Performance Optimization
- Chapter 9: Production Deployment
```
### 3. Map Prerequisite Dependencies
Create dependency mapping:
- Which chapters must be read before others?
- What external knowledge is assumed?
- Are there alternative learning paths?
- Can any chapters be read independently?
**Dependency Notation:**
- **Hard prerequisite**: Chapter 5 REQUIRES Chapter 3
- **Soft prerequisite**: Chapter 7 RECOMMENDS Chapter 4 (helpful but not essential)
- **No prerequisite**: Chapter can be read standalone
**Example Dependency Map:**
```
Chapter 1 → Chapter 2 (hard prerequisite)
Chapter 2 → Chapter 3 (hard prerequisite)
Chapter 3 → Chapter 4, Chapter 5 (hard prerequisite)
Chapter 4 → Chapter 7 (soft prerequisite)
Chapter 5 → Chapter 6 (hard prerequisite)
Chapter 6 → Chapter 8 (soft prerequisite)
```
### 4. Design Skill Scaffolding
Plan progression from simple to complex:
- Start with concrete, tangible concepts
- Build abstractions incrementally
- Introduce one new concept at a time
- Reinforce previous concepts in new contexts
- Increase cognitive load gradually
**Scaffolding Principles:**
- **Concrete before abstract**: Show examples before theory
- **Simple before complex**: One variable at a time
- **Familiar before unfamiliar**: Build on known concepts
- **Guided before independent**: Provide support initially
**Example Skill Progression:**
```
1. Use existing API (concrete, simple)
2. Understand API request/response (concrete, intermediate)
3. Design API endpoint (abstract, intermediate)
4. Implement full API (abstract, complex)
5. Optimize API architecture (abstract, advanced)
```
### 5. Validate No Knowledge Gaps
Check for missing prerequisites:
- Review each chapter's required knowledge
- Verify all prerequisites are taught earlier
- Identify any assumed knowledge not covered
- Check for circular dependencies
- Look for sudden difficulty jumps
**Gap Detection Questions:**
- Does the reader have the knowledge needed for this chapter?
- Was this concept explained in a previous chapter?
- Are we assuming prior knowledge that wasn't taught?
- Is there too large a jump from the previous chapter?
**Common Gaps:**
- Technical jargon used without definition
- Tools/frameworks used without introduction
- Concepts referenced but never explained
- Skipped intermediate steps
### 6. Assess Reader Readiness
Evaluate readiness at key transition points:
- Can readers handle the next chapter after completing this one?
- What skills should readers have at this point?
- How can readers self-assess their readiness?
- Should there be a checkpoint exercise?
**Readiness Assessment Template:**
```
After Chapter 3, readers should be able to:
✓ Write basic JavaScript functions
✓ Understand variables, loops, and conditionals
✓ Debug simple syntax errors
✓ Read and understand code examples
Before Chapter 4, readers should verify:
□ Can I write a function that takes parameters?
□ Do I understand how arrays work?
□ Can I follow code examples without confusion?
```
### 7. Identify Optional vs. Required Chapters
Mark chapter importance:
- **Required (Core)**: Essential for understanding later material
- **Recommended**: Enhances understanding but not essential
- **Optional**: Bonus content, alternative approaches, deep dives
**Labeling Example:**
```
✓ Chapter 1: Introduction (REQUIRED)
✓ Chapter 2: Setup (REQUIRED)
✓ Chapter 3: Basics (REQUIRED)
○ Chapter 4: Advanced Techniques (RECOMMENDED)
○ Chapter 5: Alternative Approaches (OPTIONAL)
✓ Chapter 6: Integration (REQUIRED)
```
### 8. Create Dependency Diagram
Visualize the learning path:
- Use flowchart or dependency graph
- Show prerequisite relationships
- Mark required vs. optional chapters
- Indicate alternative paths if applicable
**Simple Text Diagram:**
```
[Chapter 1] ──→ [Chapter 2] ──→ [Chapter 3] ──┬──→ [Chapter 4] ──→ [Chapter 7]
│
└──→ [Chapter 5] ──→ [Chapter 6] ──→ [Chapter 8]
Legend:
──→ Hard prerequisite
··→ Soft prerequisite (recommended)
[ ] Required chapter
( ) Optional chapter
```
### 9. Verify Alignment with Learning Objectives
Cross-check with stated objectives:
- Do chapter sequences support stated learning goals?
- Are learning objectives achievable with this progression?
- Does the path build the skills promised in the book description?
- Are there any objectives not covered by the learning path?
**Alignment Check:**
- Book objective: "Master API development"
- Learning path includes: API basics → design → implementation → optimization ✓
- Progression supports objective ✓
### 10. Document Learning Path
Create comprehensive learning path documentation:
**Include:**
- Visual dependency diagram
- Chapter-by-chapter prerequisite list
- Skill progression chart
- Reader readiness checkpoints
- Alternative reading paths (if applicable)
- Estimated difficulty curve
- Recommended pace (time per chapter)
**Example Documentation:**
```markdown
# Learning Path: Mastering Web APIs
## Reading Order
### Linear Path (Recommended for Beginners)
Chapters 1 → 2 → 3 → 4 → 5 → 6 → 7 → 8
### Fast Track (For Experienced Developers)
Chapters 1 → 3 → 5 → 6 → 8
(Skip chapters 2, 4, 7 if familiar with basics)
## Prerequisite Map
- Chapter 1: No prerequisites (start here)
- Chapter 2: Requires Chapter 1
- Chapter 3: Requires Chapter 2
- Chapter 4: Requires Chapter 3 (optional enhancement)
- Chapter 5: Requires Chapter 3
- Chapter 6: Requires Chapter 5
- Chapter 7: Requires Chapter 4 and 6
- Chapter 8: Requires Chapter 6
## Skill Progression
Chapters 1-3: Foundational (Beginner)
Chapters 4-6: Intermediate
Chapters 7-8: Advanced
## Reader Readiness Checkpoints
After Chapter 3: Can you create a basic API endpoint?
After Chapter 6: Can you handle authentication and errors?
After Chapter 8: Can you deploy and optimize an API?
```
### 11. Run Quality Checklists
Validate learning path quality:
- Run execute-checklist.md with learning-objectives-checklist.md
- Run execute-checklist.md with prerequisite-clarity-checklist.md
## Success Criteria
A completed learning path should have:
- [ ] Complete prerequisite dependency map
- [ ] Skill scaffolding from simple to complex
- [ ] No knowledge gaps or unexplained concepts
- [ ] Reader readiness checkpoints defined
- [ ] Optional vs. required chapters clearly marked
- [ ] Visual dependency diagram
- [ ] Alignment with stated learning objectives
- [ ] Alternative reading paths (if applicable)
- [ ] All checklists passed
## Common Pitfalls to Avoid
- **Circular dependencies**: Chapter A requires B, which requires A
- **Knowledge gaps**: Concepts used before being taught
- **Too steep progression**: Jumping from beginner to advanced without intermediate steps
- **Hidden prerequisites**: Assuming knowledge not covered in the book
- **No alternative paths**: Forcing linear reading when options exist
- **Unclear optional content**: Readers can't tell what they can skip
## Next Steps
After designing the learning path:
1. Update book outline with prerequisite information
2. Add reader readiness checkpoints to chapters
3. Include learning path diagram in book introduction or preface
4. Review with beta readers or instructional design expert
5. Update as chapter content evolves

123
expansion-packs/bmad-technical-writing/tasks/package-for-publisher.md Normal file
View File

@ -0,0 +1,123 @@
<!-- Powered by BMAD™ Core -->
# Package for Publisher
---
task:
id: package-for-publisher
name: Package for Publisher
description: Prepare complete manuscript package according to publisher specifications
persona_default: book-publisher
inputs:
- publisher-name
- submission-guidelines
- manuscript-files
steps:
- Identify target publisher (PacktPub/O'Reilly/Manning/Other)
- Gather all manuscript files (chapters, front matter, back matter)
- Collect all images and diagrams
- Verify code repository link or zip
- Format per publisher requirements
- Run publisher-specific checklist
- Create submission package (zip or folder structure)
- Include metadata file if required
- Verify all cross-references work
- Run execute-checklist.md with final-manuscript-checklist.md
output: submissions/{{publisher}}-{{book-name}}-submission.zip
---
## Purpose
Prepare a complete, properly formatted manuscript package that meets publisher submission requirements.
## Workflow Steps
### 1. Publisher-Specific Requirements
**Manning:**
- Chapters in Microsoft Word (.docx)
- Separate folder for images (PNG, 300 DPI)
- Code samples in ZIP file
- Metadata in Author Questionnaire form
**O'Reilly:**
- AsciiDoc or Markdown preferred
- Images in separate folders
- Atlas platform submission
- Follows O'Reilly style guide
**Packt:**
- Microsoft Word (.docx)
- Images embedded or separate
- Code in GitHub repository
- Specific formatting template
### 2. Gather All Files
**Manuscript Components:**
```
submission-package/
├── front-matter/
│ ├── preface.docx
│ ├── acknowledgments.docx
│ └── about-author.docx
├── chapters/
│ ├── chapter-01.docx
│ ├── chapter-02.docx
│ └── ...
├── back-matter/
│ ├── appendix-a.docx
│ ├── glossary.docx
│ └── index.docx
├── images/
│ ├── chapter-01/
│ ├── chapter-02/
│ └── ...
├── code/
│ └── code-examples.zip
├── metadata.txt
└── README.txt
```
### 3. Format Per Publisher
Apply required formatting:
- Heading styles (Heading 1, 2, 3)
- Code block formatting
- Figure captions
- Cross-reference format
- Citation style
### 4. Create Submission Package
Final packaging:
```
book-title-author-submission.zip
├── manuscript/
├── images/
├── code/
├── metadata.txt
└── submission-checklist.pdf
```
## Success Criteria
- [ ] All files gathered
- [ ] Publisher format applied
- [ ] Images at required resolution
- [ ] Code repository included
- [ ] Metadata complete
- [ ] Cross-references validated
- [ ] Final manuscript checklist passed
## Next Steps
1. Upload to publisher portal
2. Notify acquisition editor
3. Track submission status

125
expansion-packs/bmad-technical-writing/tasks/prepare-meap-chapter.md Normal file
View File

@ -0,0 +1,125 @@
<!-- Powered by BMAD™ Core -->
# Prepare MEAP Chapter
---
task:
id: prepare-meap-chapter
name: Prepare MEAP Chapter
description: Prepare chapter for Manning Early Access Program (MEAP) release
persona_default: book-publisher
inputs:
- chapter-number
- chapter-file
- book-context
steps:
- Ensure chapter works standalone (introduction includes context)
- Verify chapter doesn't require unreleased chapters
- Check author voice consistency
- Link code repository clearly
- Apply Manning MEAP-specific formatting
- Add MEAP disclaimer if needed
- Include "what's coming next" section
- Run execute-checklist.md with manning-meap-checklist.md
- Run execute-checklist.md with meap-readiness-checklist.md
- Create MEAP package
- Test chapter reads well independently
output: meap/chapter-{{n}}-meap-ready.docx
---
## Purpose
Prepare a chapter for early release through Manning's MEAP program, ensuring it provides value to early readers even before the complete book is finished.
## Workflow Steps
### 1. Make Chapter Standalone
Provide necessary context:
**Add Chapter Introduction:**
```
This chapter covers [topic]. In the previous chapter, you learned [previous topic brief summary].
In this chapter, you'll discover [current topic]. By the end, you'll be able to [learning outcomes].
Note: This is an early access chapter. Some cross-references to future chapters are placeholders.
```
### 2. No Forward References
Avoid referencing unreleased content:
```
❌ "As we'll see in Chapter 8..."
✅ "In a future chapter on deployment..."
❌ "See Section 7.3 for details"
✅ "This will be covered in detail in the final book"
```
### 3. Link Code Repository
Make code easily accessible:
```
Code Examples
All code for this chapter is available at:
https://github.com/username/book-code/tree/main/chapter-05
Download: [Download ZIP button/link]
```
### 4. Add "What's Coming Next"
Preview future content:
```
## Coming in Future Chapters
In the next chapter, you'll learn about:
- Topic 1
- Topic 2
- Topic 3
Future chapters will cover:
- Advanced patterns (Chapter 7)
- Production deployment (Chapter 9)
- Performance optimization (Chapter 10)
```
### 5. MEAP Disclaimer
Set expectations:
```
📘 MEAP Early Access Notice
This is an early access chapter. You may encounter:
- Placeholders for future cross-references
- Draft diagrams or images
- Sections marked [TBD]
Your feedback helps shape the final book! Please share thoughts at:
[feedback forum link]
```
## Success Criteria
- [ ] Chapter works standalone
- [ ] No unreleased chapter references
- [ ] Code repository linked
- [ ] MEAP formatting applied
- [ ] "What's next" section included
- [ ] Disclaimer added
- [ ] MEAP checklists passed
- [ ] Independent reading tested
## Next Steps
1. Submit to Manning MEAP portal
2. Monitor reader feedback
3. Incorporate feedback into revisions

210
expansion-packs/bmad-technical-writing/tasks/self-publish-prep.md Normal file
View File

@ -0,0 +1,210 @@
<!-- Powered by BMAD™ Core -->
# Self-Publish Prep
---
task:
id: self-publish-prep
name: Self-Publish Prep
description: Prepare book for self-publishing on Leanpub, Amazon KDP, or Gumroad
persona_default: book-publisher
inputs:
- target-platform
- book-files
- cover-design
steps:
- Choose platform (Leanpub/Amazon KDP/Gumroad)
- Format manuscript for platform (Markdown/DOCX/PDF)
- Optimize images for platform requirements
- Create book metadata (title, description, keywords, categories)
- Design or acquire cover image
- Set pricing strategy
- Create ISBN if needed (KDP provides free ISBNs)
- Format for ePub/PDF/Kindle
- Verify platform-specific requirements
- Upload and test preview
- Run execute-checklist.md with self-publishing-standards-checklist.md
output: self-publish/{{platform}}/{{book-name}}-ready/
---
## Purpose
Prepare a complete, professional book package for self-publishing platforms, ensuring quality presentation and discoverability.
## Workflow Steps
### 1. Choose Platform
**Leanpub:**
- Markdown-based
- Good for technical books
- Built-in email marketing
- Flexible pricing (minimum/suggested/maximum)
**Amazon KDP:**
- Largest audience
- Print-on-demand available
- Kindle format required
- Free ISBN provided
**Gumroad:**
- Simple, flexible
- PDF/ePub distribution
- Direct customer relationships
- No review requirements
### 2. Format for Platform
**Leanpub (Markdown):**
```markdown
# Chapter 1: Introduction
{book: true, sample: true}
This chapter introduces...
## Section 1.1
Content here...
{class: code}
```python
# Code example
```
**KDP (Word/ePub):**
- Use heading styles
- Insert page breaks
- Format code blocks
- Embed images
### 3. Create Metadata
**Title and Description:**
```
Title: Mastering Web APIs: A Practical Guide to REST and GraphQL
Subtitle: Build, Secure, and Scale Production-Ready APIs
Description:
Learn to design, build, and deploy production-ready APIs with this hands-on guide.
Covers REST, GraphQL, authentication, rate limiting, and more. Includes 50+ code
examples in Python and Node.js.
What you'll learn:
• RESTful API design principles
• GraphQL schema design
• JWT authentication
• Rate limiting and caching
• Production deployment strategies
```
**Keywords/Categories:**
```
Keywords: API, REST, GraphQL, web development, Python, Node.js, authentication
Categories:
- Computers > Programming > Internet
- Computers > Web > Web Services
- Computers > Languages > Python
```
### 4. Cover Design
Requirements:
- **KDP**: 2560 x 1600 px minimum
- **Leanpub**: 1600 x 2400 px recommended
- **Readable thumbnail**: Text visible at small sizes
- **Professional**: Use Canva, 99designs, or hire designer
### 5. Set Pricing
Pricing strategy:
**Leanpub Pricing Model:**
```
Minimum: $9.99 (reader can pay more)
Suggested: $29.99
Maximum: $99
```
**KDP Pricing:**
```
eBook: $9.99 - $29.99 (70% royalty tier)
Print: $39.99 (based on page count + margin)
```
### 6. ISBN (Optional)
- **KDP**: Provides free ISBN
- **Self-purchase**: $125 for single ISBN from Bowker (US)
- **Not required** for eBooks on most platforms
### 7. Format for Distribution
**ePub (KDP, Gumroad):**
- Use Calibre or Pandoc for conversion
- Test on multiple e-readers
- Validate with ePub validator
**PDF (Leanpub, Gumroad):**
- High-quality PDF export
- Embedded fonts
- Optimized images
**Kindle (KDP):**
- Upload DOCX or use Kindle Create tool
- KDP converts to .mobi/.azw
### 8. Platform-Specific Requirements
**KDP:**
- Copyright page required
- Table of contents with links
- "Look Inside" preview (first 10%)
**Leanpub:**
- Subset.txt for sample chapters
- Book.txt for chapter ordering
- Metadata in Book.txt
### 9. Upload and Preview
Test before publishing:
- Upload to platform
- Generate preview
- Test on multiple devices (Kindle app, iPad, PDF reader)
- Check formatting, images, code blocks
- Verify table of contents links
### 10. Run Quality Checklist
- Run execute-checklist.md with self-publishing-standards-checklist.md
## Success Criteria
- [ ] Platform selected
- [ ] Manuscript formatted correctly
- [ ] Images optimized
- [ ] Metadata complete (title, description, keywords)
- [ ] Professional cover design
- [ ] Pricing set
- [ ] ISBN acquired (if needed)
- [ ] ePub/PDF/Kindle formats created
- [ ] Preview tested on target devices
- [ ] Self-publishing checklist passed
## Next Steps
1. Publish to platform
2. Set up marketing (email list, social media)
3. Monitor sales and reviews
4. Plan updates and revisions

557
expansion-packs/bmad-technical-writing/tasks/setup-code-repository.md Normal file
View File

@ -0,0 +1,557 @@
<!-- Powered by BMAD™ Core -->
# Setup Code Repository
---
task:
id: setup-code-repository
name: Setup Code Repository
description: Initialize and structure GitHub repository for book code examples
persona_default: sample-code-maintainer
inputs:
- book-name
- programming-language
- target-platforms
steps:
- Initialize GitHub repository
- Create chapter-based folder structure
- Add README.md with repository overview
- Create requirements or package files per chapter
- Set up testing infrastructure
- Create .gitignore for language-specific files
- Add LICENSE file
- Document version and platform requirements
- Create CI/CD pipeline (optional)
- Add contribution guidelines if open-source
- Run execute-checklist.md with repository-quality-checklist.md
output: Code repository at https://github.com/{{org}}/{{repo-name}}
---
## Purpose
This task guides you through creating a well-organized, professional code repository that accompanies your technical book. Readers should be able to clone the repository and immediately start working with the code examples.
## Prerequisites
Before starting this task:
- GitHub account created
- Git installed locally
- Book outline with chapter structure
- Understanding of target programming language ecosystem
- Knowledge of target platforms (Windows/Mac/Linux)
## Workflow Steps
### 1. Initialize GitHub Repository
Create the repository:
**Steps:**
1. Go to GitHub.com and create new repository
2. Choose repository name (e.g., `mastering-web-apis-code`)
3. Add description: "Code examples for [Book Title]"
4. Choose public or private (usually public for published books)
5. Initialize with README (we'll replace it)
6. Clone locally: `git clone https://github.com/yourusername/repo-name.git`
**Naming Conventions:**
- Use book title or abbreviation
- Append `-code` or `-examples`
- Use lowercase with hyphens
- Examples: `python-data-science-code`, `react-book-examples`
### 2. Create Chapter-Based Folder Structure
Organize by chapters:
**Standard Structure:**
```
repo-root/
├── chapter-01/
│ ├── example-01-hello-world/
│ ├── example-02-variables/
│ └── README.md
├── chapter-02/
│ ├── example-01-functions/
│ ├── example-02-classes/
│ └── README.md
├── chapter-03/
│ └── ...
├── appendix-a/
├── bonus-content/
├── tests/
├── .github/
│ └── workflows/
├── .gitignore
├── LICENSE
├── README.md
└── requirements.txt (or package.json, etc.)
```
**Alternative Structure (for small books):**
```
repo-root/
├── src/
│ ├── ch01_example1.py
│ ├── ch01_example2.py
│ ├── ch02_example1.py
│ └── ...
├── tests/
├── README.md
└── requirements.txt
```
**Create Folders:**
```bash
mkdir -p chapter-{01..12}
mkdir -p tests
mkdir -p .github/workflows
```
### 3. Add README.md with Repository Overview
Create comprehensive README:
**README Template:**
```markdown
# [Book Title] - Code Examples
Code examples and exercises from **[Book Title]** by [Author Name].
## About This Repository
This repository contains all code examples from the book, organized by chapter. Each example is self-contained and includes:
- Working code with comments
- Setup instructions
- Expected output
- Common troubleshooting tips
## Prerequisites
- [Language] version X.X or higher
- [Tool/Framework] (optional)
- Basic understanding of [concepts]
## Installation
### Option 1: Clone Entire Repository
```bash
git clone https://github.com/username/repo-name.git
cd repo-name
```
### Option 2: Download Specific Chapter
Navigate to the chapter folder and download individual examples.
## Setup
1. Install dependencies:
```bash
[package manager install command]
```
2. Verify installation:
```bash
[verification command]
```
3. Run tests (optional):
```bash
[test command]
```
## Repository Structure
- `chapter-01/` - Introduction and basics
- `chapter-02/` - [Chapter topic]
- `chapter-03/` - [Chapter topic]
- ...
- `tests/` - Automated tests for code examples
- `appendix-a/` - Additional resources
## Usage
Each chapter folder contains a README with:
- Learning objectives for that chapter
- Setup instructions specific to examples
- How to run the code
- Expected output
Navigate to a chapter and follow its README.
## Requirements
- [Language]: [Version]
- [Framework/Library]: [Version]
- [Platform]: [Supported platforms]
See `requirements.txt` (or `package.json`, `Gemfile`, etc.) for complete dependency list.
## Running Examples
```bash
cd chapter-03/example-01-api-basics
[command to run example]
```
## Testing
```bash
[command to run all tests]
```
## Contributing
Found a bug or improvement? Please [open an issue](link) or submit a pull request.
## License
[License type - MIT, Apache 2.0, etc.]
## About the Book
**[Book Title]**
By [Author Name]
Published by [Publisher]
[Purchase link]
## Support
- [Book website](link)
- [Author contact](link)
- [Errata page](link)
```
### 4. Create Requirements/Package Files Per Chapter
Define dependencies:
**For Python:**
Create `requirements.txt` in root and per-chapter if dependencies differ:
```
# requirements.txt (root)
requests==2.31.0
pytest==7.4.0
black==23.7.0
# chapter-03/requirements.txt (if different)
requests==2.31.0
flask==2.3.0
```
**For Node.js:**
Create `package.json`:
```json
{
"name": "book-code-examples",
"version": "1.0.0",
"description": "Code examples for [Book Title]",
"scripts": {
"test": "jest",
"lint": "eslint ."
},
"dependencies": {
"express": "^4.18.0"
},
"devDependencies": {
"jest": "^29.5.0",
"eslint": "^8.43.0"
},
"engines": {
"node": ">=18.0.0"
}
}
```
**For Java:**
Create `pom.xml` (Maven) or `build.gradle` (Gradle)
**Version Pinning:**
- Pin exact versions for reproducibility
- Document why specific versions are required
- Test with version ranges if supporting multiple versions
### 5. Set Up Testing Infrastructure
Add automated tests:
**Python (pytest):**
```python
# tests/test_chapter01.py
import pytest
from chapter01.example01 import hello_world
def test_hello_world():
result = hello_world()
assert result == "Hello, World!"
```
**Node.js (Jest):**
```javascript
// tests/chapter01.test.js
const { helloWorld } = require('../chapter-01/example-01/index');
test('returns hello world', () => {
expect(helloWorld()).toBe('Hello, World!');
});
```
**Test Structure:**
```
tests/
├── test_chapter01.py
├── test_chapter02.py
├── test_chapter03.py
└── conftest.py (pytest configuration)
```
### 6. Create .gitignore
Exclude unnecessary files:
**Python .gitignore:**
```
# Python
__pycache__/
*.py[cod]
*$py.class
*.so
.Python
venv/
env/
ENV/
.venv
# IDE
.vscode/
.idea/
*.swp
*.swo
# OS
.DS_Store
Thumbs.db
# Testing
.coverage
htmlcov/
.pytest_cache/
```
**Node.js .gitignore:**
```
# Node
node_modules/
npm-debug.log*
yarn-debug.log*
yarn-error.log*
# IDE
.vscode/
.idea/
# OS
.DS_Store
# Testing
coverage/
.nyc_output/
```
### 7. Add LICENSE File
Choose appropriate license:
**MIT License (permissive):**
```
MIT License
Copyright (c) [year] [fullname]
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction...
```
**Apache 2.0 (permissive with patent grant):**
Use for enterprise-friendly code.
**Creative Commons (for content):**
Consider for tutorials/documentation.
**How to Choose:**
- MIT: Simple, permissive, widely used
- Apache 2.0: Patent protection, enterprise-friendly
- GPL: Copyleft, requires derivative works to be open source
- Proprietary: All rights reserved (unusual for book code)
### 8. Document Version and Platform Requirements
Specify compatibility:
**Create REQUIREMENTS.md or include in README:**
```markdown
## System Requirements
### Supported Platforms
- ✅ macOS 11+ (Big Sur or later)
- ✅ Windows 10/11
- ✅ Linux (Ubuntu 20.04+, Fedora 35+, Debian 11+)
### Software Requirements
- Python 3.11 or higher (tested on 3.11, 3.12)
- pip 23.0+
- Git 2.30+
### Optional Tools
- Docker 20.10+ (for containerized examples)
- VS Code 1.75+ (recommended IDE)
```
### 9. Create CI/CD Pipeline (Optional but Recommended)
Automate testing:
**GitHub Actions (.github/workflows/test.yml):**
```yaml
name: Test Code Examples
on: [push, pull_request]
jobs:
test:
runs-on: ${{ matrix.os }}
strategy:
matrix:
os: [ubuntu-latest, windows-latest, macos-latest]
python-version: ['3.11', '3.12']
steps:
- uses: actions/checkout@v3
- name: Set up Python
uses: actions/setup-python@v4
with:
python-version: ${{ matrix.python-version }}
- name: Install dependencies
run: |
pip install -r requirements.txt
- name: Run tests
run: |
pytest tests/
```
**Benefits of CI/CD:**
- Catch breaking changes immediately
- Verify cross-platform compatibility
- Test multiple language versions
- Build confidence for readers
### 10. Add Contribution Guidelines
If open-source:
**Create CONTRIBUTING.md:**
```markdown
# Contributing
Thank you for your interest in improving these code examples!
## Reporting Issues
- Check existing issues first
- Provide code example and error message
- Specify your platform and version
## Submitting Pull Requests
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Ensure all tests pass
6. Submit pull request with clear description
## Code Style
- Follow [language-specific style guide]
- Run linter before committing
- Add comments for complex logic
```
### 11. Validate Repository Quality
Run checklist:
- Run execute-checklist.md with repository-quality-checklist.md
## Success Criteria
A completed code repository should have:
- [ ] GitHub repository initialized and cloned
- [ ] Logical folder structure (chapter-based or src-based)
- [ ] Comprehensive README.md
- [ ] Dependencies documented (requirements.txt, package.json, etc.)
- [ ] Testing infrastructure set up
- [ ] Proper .gitignore for language
- [ ] LICENSE file included
- [ ] Version and platform requirements documented
- [ ] CI/CD pipeline configured (optional)
- [ ] Contribution guidelines (if open-source)
- [ ] Repository quality checklist passed
## Common Pitfalls to Avoid
- **No structure**: Dumping all code in root directory
- **Missing dependencies**: Not documenting required packages
- **No README**: Readers don't know how to use the repository
- **Untested code**: Code works on author's machine only
- **No license**: Legal uncertainty for readers
- **Platform assumptions**: Code only works on one OS
- **Outdated dependencies**: Using deprecated package versions
## Next Steps
After setting up the repository:
1. Add code examples as you write chapters
2. Test on all supported platforms
3. Update README as repository grows
4. Set up GitHub Pages for documentation (optional)
5. Link repository prominently in book's front matter

100
expansion-packs/bmad-technical-writing/tasks/take-screenshots.md Normal file
View File

@ -0,0 +1,100 @@
<!-- Powered by BMAD™ Core -->
# Take Screenshots
---
task:
id: take-screenshots
name: Take Screenshots
description: Capture, annotate, and prepare high-quality screenshots for technical documentation
persona_default: screenshot-specialist
inputs:
- screenshot-specifications
- required-resolution
- annotation-requirements
steps:
- Review screenshot specifications from diagram specs
- Prepare clean demonstration environment
- Capture screenshots at required resolution (300 DPI minimum)
- Add annotations (arrows, callouts, highlights)
- Crop to relevant area
- Ensure text is readable
- Apply consistent styling (border, shadow, etc.)
- Save in required format (PNG, JPEG)
- Name files descriptively (chapter-02-figure-03.png)
- Run execute-checklist.md with screenshot-quality-checklist.md
- Run execute-checklist.md with accessibility-checklist.md
output: images/screenshots/{{descriptive-name}}.png
---
## Purpose
Create professional, readable screenshots that enhance understanding. Quality screenshots are essential for UI documentation, tutorials, and step-by-step guides.
## Workflow Steps
### 1. Prepare Clean Environment
Set up for capture:
- Use clean desktop (no personal info)
- Close unnecessary windows
- Use default theme unless demonstrating customization
- Zoom to appropriate level (125-150% for clarity)
- Use realistic but safe demo data
### 2. Capture at High Resolution
Quality requirements:
- **Minimum 300 DPI** for print
- **Retina/HiDPI** for web (2x resolution)
- **Full window** vs **focused area** based on context
- **Consistent dimensions** for similar screenshots
### 3. Annotate Effectively
Add helpful annotations:
- **Arrows**: Point to specific UI elements
- **Numbered callouts**: Reference in text
- **Highlights**: Draw attention to key areas
- **Red boxes**: Emphasize important elements
### 4. Apply Consistent Styling
Visual consistency:
- Same annotation colors across book
- Consistent border/shadow treatment
- Uniform font for labels
- Matching screenshot dimensions for similar content
### 5. Name Files Descriptively
File naming convention:
```
chapter-02-django-admin-login.png
chapter-03-api-response-json.png
chapter-05-error-message-detail.png
```
## Success Criteria
- [ ] High resolution (300 DPI minimum)
- [ ] Readable text
- [ ] Clear annotations
- [ ] Consistent styling
- [ ] Descriptive file names
- [ ] Screenshot quality checklist passed
- [ ] Accessibility checklist passed
## Next Steps
1. Add screenshots to manuscript
2. Reference in figure captions
3. Include alt text for accessibility

256
expansion-packs/bmad-technical-writing/tasks/validate-cross-references.md Normal file
View File

@ -0,0 +1,256 @@
<!-- Powered by BMAD™ Core -->
# Validate Cross References
---
task:
id: validate-cross-references
name: Validate Cross References
description: Verify all cross-references, internal links, external URLs, and citations are accurate
persona_default: technical-editor
inputs:
- manuscript-files
- reference-type
- validation-scope
steps:
- Extract all cross-references (Chapter X, see Section Y, etc.)
- Verify chapter and section numbers are correct
- Check page number references (if used)
- Validate internal links work
- Verify external links (URLs) are accessible
- Check glossary references
- Validate index references
- Ensure bidirectional references (if A references B does B note A)
- Test all code repository links
- Update broken or outdated references
- Create cross-reference validation log
output: docs/validation/cross-reference-validation-log.md
---
## Purpose
Ensure all references, links, and citations are accurate and functional, preventing reader frustration and maintaining book credibility.
## Workflow Steps
### 1. Extract All Cross-References
Find all references:
**Internal references:**
- "See Chapter 5"
- "As discussed in Section 3.2"
- "Refer to Figure 7.4"
- "Exercise 2.3 demonstrates..."
- "Appendix B contains..."
**External references:**
- URLs to documentation
- Code repository links
- API documentation links
- Tool download links
### 2. Verify Chapter/Section Numbers
Check accuracy:
```markdown
✅ Correct:
"In Chapter 3, we learned about REST APIs..." [Chapter 3 exists and covers REST]
❌ Incorrect:
"See Chapter 8 for deployment details" [Chapter 8 is about testing, not deployment]
```
**Validation script (conceptual):**
```python
# Check all "Chapter X" references
references = extract_references(manuscript, pattern=r'Chapter \d+')
for ref in references:
chapter_num = ref.chapter_number
if chapter_num > total_chapters:
print(f"ERROR: Reference to non-existent {ref}")
```
### 3. Check Page References
Validate page numbers:
```markdown
⚠️ During manuscript phase:
"See page [TK]" or "See Chapter 3" (not page numbers)
✅ During page proof phase:
"See page 87 for details"
```
### 4. Validate Internal Links
Test document links:
**Markdown:**
```markdown
[Link to Section 3.2](#section-32)
# Check target exists:
<a name="section-32"></a>
## 3.2 API Design Patterns
```
**HTML/ePub:**
```html
<a href="#chapter-03">Chapter 3</a>
<!-- Verify target exists: -->
<div id="chapter-03">...</div>
```
### 5. Verify External Links
Test URL accessibility:
```python
# Check all URLs
import requests
urls = extract_urls(manuscript)
broken_links = []
for url in urls:
try:
response = requests.head(url, timeout=5, allow_redirects=True)
if response.status_code >= 400:
broken_links.append((url, response.status_code))
except requests.RequestException as e:
broken_links.append((url, str(e)))
# Report broken links
for url, error in broken_links:
print(f"BROKEN: {url} - {error}")
```
**Common issues:**
- 404 Not Found (page removed)
- Moved permanently (update URL)
- SSL certificate errors
- Timeout (site down)
### 6. Check Glossary References
Verify glossary terms:
```markdown
The API uses JWT (see Glossary) for authentication.
[Verify "JWT" entry exists in glossary]
```
### 7. Validate Index References
Cross-check index:
```markdown
Index entry: "Authentication, 45, 78, 103"
[Verify pages 45, 78, and 103 actually discuss authentication]
```
### 8. Ensure Bidirectional References
Check both directions:
```markdown
Chapter 3 says: "Authentication is covered in Chapter 7"
[Verify Chapter 7 mentions being referenced from Chapter 3, if appropriate]
✅ Chapter 7: "As introduced in Chapter 3, authentication..."
```
### 9. Test Code Repository Links
Validate repo access:
```markdown
Code for this chapter: https://github.com/author/book/tree/main/chapter-03
[Test link opens correctly]
[Verify chapter-03 folder exists]
[Check README.md in folder is accurate]
```
### 10. Create Validation Log
Document findings:
```markdown
# Cross-Reference Validation Log
Date: 2024-01-15
Validator: [Name]
Manuscript Version: Draft 3.2
## Summary
- Total references checked: 247
- Valid references: 239 (96.8%)
- Broken references: 8 (3.2%)
## Issues Found
### High Priority (Broken Links)
1. Chapter 5, Line 234: "See Chapter 9" → Chapter 9 doesn't exist (was split into Ch 9-10)
- **Fix**: Update to "See Chapters 9 and 10"
2. Chapter 7, Line 89: https://oldapi.example.com/docs → 404 Not Found
- **Fix**: Update to https://api.example.com/v2/docs
### Medium Priority (Outdated References)
3. Chapter 3, Line 145: "Appendix A" → Content moved to Appendix B
- **Fix**: Update reference
### Low Priority (Inconsistencies)
4. Chapter 4: Uses "Section 3.2" and "section 3.2" inconsistently
- **Fix**: Standardize capitalization
## Verification Status
| Reference Type | Total | Valid | Broken |
|----------------|-------|-------|--------|
| Chapter refs | 87 | 85 | 2 |
| Section refs | 64 | 64 | 0 |
| Figure refs | 42 | 40 | 2 |
| External URLs | 31 | 27 | 4 |
| Code repo links | 18 | 18 | 0 |
| Glossary refs | 5 | 5 | 0 |
## Next Steps
1. Fix all high-priority broken references
2. Update outdated references
3. Standardize reference formatting
4. Re-validate after changes
```
## Success Criteria
- [ ] All cross-references extracted
- [ ] Chapter/section numbers verified
- [ ] Page references validated (if applicable)
- [ ] Internal links tested
- [ ] External URLs checked for accessibility
- [ ] Glossary references confirmed
- [ ] Index references validated
- [ ] Bidirectional references verified
- [ ] Code repository links tested
- [ ] Validation log created with findings
## Next Steps
1. Fix all broken references
2. Update outdated links
3. Standardize reference formatting
4. Re-validate after corrections
5. Include validation in revision process

390
expansion-packs/bmad-technical-writing/tasks/version-matrix-check.md Normal file
View File

@ -0,0 +1,390 @@
<!-- Powered by BMAD™ Core -->
# Version Matrix Check
---
task:
id: version-matrix-check
name: Version Matrix Check
description: Test code examples across multiple versions and platforms for compatibility
persona_default: version-manager
inputs:
- target-versions
- target-platforms
- code-examples-location
steps:
- Define target versions for testing
- Define target platforms (Windows/macOS/Linux as applicable)
- Set up testing environment for each version
- Run all code examples on version matrix
- Document version-specific behaviors
- Note breaking changes between versions
- Test platform-specific code (file paths, etc.)
- Create version compatibility matrix
- Update documentation with version requirements
- Document version-specific workarounds
- Run execute-checklist.md with version-compatibility-checklist.md
- Run execute-checklist.md with cross-platform-checklist.md
output: docs/version-compatibility/{{book-name}}-version-matrix.md
---
## Purpose
This task ensures all code examples work correctly across specified versions and platforms. Version compatibility testing prevents reader frustration and builds confidence in your code examples.
## Prerequisites
Before starting this task:
- All code examples completed
- Target versions identified (e.g., Python 3.10, 3.11, 3.12)
- Access to testing environments for each version
- Understanding of platform-specific differences
## Workflow Steps
### 1. Define Target Versions
Specify which versions to support:
**Example Version Targets:**
```yaml
Language: Python
Versions:
- 3.10 (minimum supported)
- 3.11 (recommended)
- 3.12 (latest)
Language: Node.js
Versions:
- 18.x LTS
- 20.x LTS
- 21.x Current
```
**Version Selection Criteria:**
- Currently maintained versions (not EOL)
- Versions readers likely use
- Breaking changes between versions
- LTS (Long Term Support) versions preferred
### 2. Define Target Platforms
Identify platform requirements:
**Platform Matrix:**
```
✅ Windows 10/11
✅ macOS 12+ (Monterey or later)
✅ Linux (Ubuntu 20.04+, Fedora 35+)
```
**Platform-Specific Considerations:**
- File path separators (/ vs \)
- Line endings (LF vs CRLF)
- Case sensitivity (macOS/Linux vs Windows)
- Shell differences (bash vs PowerShell vs cmd)
- Platform-specific APIs
### 3. Set Up Testing Environment
Create isolated environments:
**Python - Using pyenv:**
```bash
# Install multiple Python versions
pyenv install 3.10.12
pyenv install 3.11.5
pyenv install 3.12.0
# Create virtual environments
pyenv virtualenv 3.10.12 book-py310
pyenv virtualenv 3.11.5 book-py311
pyenv virtualenv 3.12.0 book-py312
```
**Node.js - Using nvm:**
```bash
# Install multiple Node versions
nvm install 18
nvm install 20
nvm install 21
# Test on specific version
nvm use 18
npm test
```
**Docker - For cross-platform:**
```dockerfile
# Dockerfile.test-matrix
FROM python:3.10
COPY . /app
WORKDIR /app
RUN pip install -r requirements.txt
CMD ["pytest", "tests/"]
```
### 4. Run All Code Examples
Execute systematic testing:
**Testing Script Example:**
```bash
#!/bin/bash
# test-versions.sh
VERSIONS=("3.10" "3.11" "3.12")
for version in "${VERSIONS[@]}"; do
echo "Testing on Python $version"
pyenv local $version
pip install -r requirements.txt
pytest tests/ --verbose
if [ $? -ne 0 ]; then
echo "❌ Tests failed on Python $version"
else
echo "✅ Tests passed on Python $version"
fi
done
```
**Automated Testing:**
```yaml
# GitHub Actions matrix testing
strategy:
matrix:
python-version: ['3.10', '3.11', '3.12']
os: [ubuntu-latest, windows-latest, macos-latest]
```
### 5. Document Version-Specific Behaviors
Note differences between versions:
**Example Documentation:**
```markdown
## Version-Specific Behaviors
### Python 3.10 vs 3.11
**Pattern Matching (3.10+):**
```python
# Works in 3.10+, syntax error in 3.9
match status:
case 200:
return "Success"
case 404:
return "Not Found"
```
**Improved Error Messages (3.11+):**
Python 3.11 provides more detailed traceback information.
### Python 3.11 vs 3.12
**ExceptionGroup (3.11+):**
New exception handling for multiple exceptions.
**Type Hinting Improvements (3.12+):**
Support for generic type aliases using `type` keyword.
```
### 6. Note Breaking Changes
Identify incompatibilities:
**Breaking Change Documentation:**
```markdown
## Breaking Changes
### Python 3.10 → 3.11
- ✅ **Backward Compatible**: All 3.10 code works in 3.11
- ⚠️ **Deprecations**: distutils deprecated, use setuptools
### Python 3.11 → 3.12
- ✅ **Backward Compatible**: All 3.11 code works in 3.12
- ⚠️ **Removed**: wstr removed from Unicode objects (internal change)
### Node.js 18 → 20
- ⚠️ **OpenSSL Update**: Updated to OpenSSL 3.0 (may affect crypto)
- ✅ **New Features**: V8 11.3, improved fetch() support
```
### 7. Test Platform-Specific Code
Verify cross-platform compatibility:
**File Path Handling:**
```python
# ❌ Platform-specific (breaks on Windows)
path = "data/files/example.txt"
# ✅ Cross-platform
from pathlib import Path
path = Path("data") / "files" / "example.txt"
```
**Environment Variables:**
```python
# ❌ Shell-specific
os.system("export API_KEY=secret") # Unix only
# ✅ Cross-platform
os.environ["API_KEY"] = "secret"
```
**Line Endings:**
```python
# Always specify newline handling
with open("file.txt", "w", newline="\n") as f:
f.write("text")
```
### 8. Create Version Compatibility Matrix
Build comprehensive matrix:
**Version Compatibility Matrix:**
```markdown
| Feature / Example | Python 3.10 | Python 3.11 | Python 3.12 |
|-------------------|-------------|-------------|-------------|
| Chapter 1 Examples | ✅ | ✅ | ✅ |
| Chapter 2 Examples | ✅ | ✅ | ✅ |
| Chapter 3 (Pattern Matching) | ✅ | ✅ | ✅ |
| Chapter 4 (ExceptionGroup) | ❌ | ✅ | ✅ |
| Chapter 5 (Type Aliases) | ❌ | ❌ | ✅ |
| Platform Tests | Windows | macOS | Linux |
|----------------|---------|-------|-------|
| All Examples | ✅ | ✅ | ✅ |
| File I/O | ✅ | ✅ | ✅ |
| Networking | ✅ | ✅ | ✅ |
| Subprocess | ⚠️* | ✅ | ✅ |
*Requires PowerShell-specific commands
```
### 9. Update Documentation
Add version requirements:
**Update README.md:**
```markdown
## Version Requirements
### Minimum Requirements
- Python 3.10 or higher
### Recommended
- Python 3.11+ (better error messages, improved performance)
### Version-Specific Chapters
- **Chapter 4**: Requires Python 3.11+ for ExceptionGroup examples
- **Chapter 5**: Requires Python 3.12+ for type alias syntax
### Platform Support
All examples tested on:
- ✅ Windows 10/11
- ✅ macOS 12+
- ✅ Linux (Ubuntu 20.04+)
```
### 10. Document Workarounds
Provide version-specific solutions:
**Workaround Documentation:**
```markdown
## Version-Specific Workarounds
### Using Pattern Matching on Python 3.9
If you must use Python 3.9, replace pattern matching with if/elif:
```python
# Python 3.10+ (preferred)
match status:
case 200: return "Success"
case 404: return "Not Found"
# Python 3.9 workaround
if status == 200:
return "Success"
elif status == 404:
return "Not Found"
```
### ExceptionGroup Backport for Python 3.10
```bash
pip install exceptiongroup # Backport package
```
```
### 11. Run Quality Checklists
Validate compatibility:
- Run execute-checklist.md with version-compatibility-checklist.md
- Run execute-checklist.md with cross-platform-checklist.md
## Success Criteria
A completed version matrix check should have:
- [ ] Target versions clearly defined
- [ ] Target platforms identified
- [ ] All versions tested in isolated environments
- [ ] All code examples executed on version matrix
- [ ] Version-specific behaviors documented
- [ ] Breaking changes identified and noted
- [ ] Platform-specific code tested
- [ ] Complete compatibility matrix created
- [ ] Version requirements in README updated
- [ ] Workarounds documented for older versions
- [ ] All checklists passed
## Common Pitfalls to Avoid
- **Testing on one version only**: Readers use diverse environments
- **Ignoring platform differences**: File paths, line endings, shell commands
- **No version requirements**: Readers don't know what to install
- **Missing workarounds**: Forcing readers to upgrade unnecessarily
- **Outdated version testing**: Supporting EOL versions
- **No CI/CD for versions**: Manual testing is error-prone
## Next Steps
After completing version matrix check:
1. Update book's system requirements section
2. Add version badges to repository README
3. Set up CI/CD to test all versions automatically
4. Note version requirements in chapter introductions where relevant
5. Provide version-specific code variations where necessary

111
expansion-packs/bmad-technical-writing/templates/glossary-entry-tmpl.yaml Normal file
View File

@ -0,0 +1,111 @@
# <!-- Powered by BMAD™ Core -->
---
template:
id: glossary-entry
name: Glossary Entry
version: 1.0
description: Define individual glossary term with concise definition, context, and cross-references
output:
format: markdown
filename: "glossary-{{term_id}}.md"
workflow:
elicitation: true
allow_skip: false
sections:
- id: term
title: Term
instruction: |
Provide the term to be defined:
- Exact spelling and capitalization
- Alternative spellings or variations (if any)
- Acronym expansion (if applicable)
- Pronunciation guide (if non-obvious)
Example: "API (Application Programming Interface)"
elicit: true
- id: definition
title: Definition
instruction: |
Write a clear, concise definition (1-2 sentences maximum):
- Use simple, direct language
- Define in terms the target audience understands
- Avoid circular definitions (don't use term in its definition)
- Focus on what it IS, not just what it does
Example: "An API is a set of rules and protocols that allows different software applications to communicate with each other."
elicit: true
- id: context
title: Context and Usage
instruction: |
Provide context for when and how the term is used:
- Common usage scenarios
- Why it matters in this book's context
- Typical example or analogy
- When readers will encounter this term
Example: "APIs are used throughout this book to demonstrate how web services exchange data. You'll build several APIs starting in Chapter 3."
- id: example
title: Usage Example
instruction: |
Provide a concrete example showing the term in use:
- Code snippet (if technical term)
- Sentence demonstrating proper usage
- Real-world application
- Visual example if helpful
Example code:
```python
# Using a weather API to get current temperature
response = requests.get('https://api.weather.com/current')
temperature = response.json()['temp']
```
Example sentence: "The mobile app calls the backend API to retrieve user data."
- id: related_terms
title: Related Terms
instruction: |
List related glossary terms or concepts:
- Similar or contrasting terms
- Broader or narrower concepts
- Terms often used together
- Prerequisites for understanding this term
Format as bulleted list with brief explanations:
- REST API: A specific architectural style for APIs
- Endpoint: A specific URL path in an API
- HTTP: The protocol most web APIs use for communication
Use "See also [Term]" format for cross-references.
- id: chapter_references
title: Chapter References
instruction: |
List where this term appears in the book:
- First introduction (definition) chapter
- Chapters with significant coverage
- Where term is applied in practice
- Related exercises or examples
Example:
- Introduced: Chapter 3, page 45
- Main coverage: Chapter 4-6
- Applied in project: Chapter 8
- id: common_misconceptions
title: Common Misconceptions (Optional)
instruction: |
Address frequent misunderstandings:
- What people often think the term means (but doesn't)
- Common confusions with similar terms
- Clarify nuances or edge cases
Example: "APIs are not the same as databases. An API is an interface that may provide access to a database, but the two are distinct components."
- id: additional_resources
title: Additional Resources (Optional)
instruction: |
Provide links or references for deeper learning:
- Official documentation
- Standards or specifications (RFC, W3C, etc.)
- Authoritative blog posts or articles
- Related chapters in this book
Keep list short (2-3 items maximum).