From abcd82e20d3f2ee9d2c91a13ace2486e2dd19fd5 Mon Sep 17 00:00:00 2001 From: Joshua Magady Date: Tue, 21 Oct 2025 02:30:34 -0500 Subject: [PATCH] feat: add checklists and templates for sprint 5 --- .../bmad-technical-writing/README.md | 40 +- .../agents/learning-path-designer.md | 104 ++++ .../agents/sample-code-maintainer.md | 102 ++++ .../agents/version-manager.md | 100 ++++ .../checklists/book-proposal-checklist.md | 134 +++++ .../checklists/citation-accuracy-checklist.md | 83 +++ .../checklists/cross-platform-checklist.md | 76 +++ .../checklists/final-manuscript-checklist.md | 134 +++++ .../inclusive-language-checklist.md | 80 +++ .../index-completeness-checklist.md | 82 +++ .../checklists/meap-readiness-checklist.md | 140 +++++ .../checklists/readability-checklist.md | 83 +++ .../repository-quality-checklist.md | 141 +++++ .../self-publishing-standards-checklist.md | 152 +++++ .../bmad-technical-writing/config.yaml | 37 +- .../tasks/create-appendix.md | 213 +++++++ .../tasks/create-index-entries.md | 157 +++++ .../tasks/create-preface.md | 253 ++++++++ .../tasks/create-solutions.md | 341 +++++++++++ .../tasks/design-diagram-set.md | 211 +++++++ .../tasks/design-learning-path.md | 335 +++++++++++ .../tasks/package-for-publisher.md | 123 ++++ .../tasks/prepare-meap-chapter.md | 125 ++++ .../tasks/self-publish-prep.md | 210 +++++++ .../tasks/setup-code-repository.md | 557 ++++++++++++++++++ .../tasks/take-screenshots.md | 100 ++++ .../tasks/validate-cross-references.md | 256 ++++++++ .../tasks/version-matrix-check.md | 390 ++++++++++++ .../templates/glossary-entry-tmpl.yaml | 111 ++++ 29 files changed, 4846 insertions(+), 24 deletions(-) create mode 100644 expansion-packs/bmad-technical-writing/agents/learning-path-designer.md create mode 100644 expansion-packs/bmad-technical-writing/agents/sample-code-maintainer.md create mode 100644 expansion-packs/bmad-technical-writing/agents/version-manager.md create mode 100644 expansion-packs/bmad-technical-writing/checklists/book-proposal-checklist.md create mode 100644 expansion-packs/bmad-technical-writing/checklists/citation-accuracy-checklist.md create mode 100644 expansion-packs/bmad-technical-writing/checklists/cross-platform-checklist.md create mode 100644 expansion-packs/bmad-technical-writing/checklists/final-manuscript-checklist.md create mode 100644 expansion-packs/bmad-technical-writing/checklists/inclusive-language-checklist.md create mode 100644 expansion-packs/bmad-technical-writing/checklists/index-completeness-checklist.md create mode 100644 expansion-packs/bmad-technical-writing/checklists/meap-readiness-checklist.md create mode 100644 expansion-packs/bmad-technical-writing/checklists/readability-checklist.md create mode 100644 expansion-packs/bmad-technical-writing/checklists/repository-quality-checklist.md create mode 100644 expansion-packs/bmad-technical-writing/checklists/self-publishing-standards-checklist.md create mode 100644 expansion-packs/bmad-technical-writing/tasks/create-appendix.md create mode 100644 expansion-packs/bmad-technical-writing/tasks/create-index-entries.md create mode 100644 expansion-packs/bmad-technical-writing/tasks/create-preface.md create mode 100644 expansion-packs/bmad-technical-writing/tasks/create-solutions.md create mode 100644 expansion-packs/bmad-technical-writing/tasks/design-diagram-set.md create mode 100644 expansion-packs/bmad-technical-writing/tasks/design-learning-path.md create mode 100644 expansion-packs/bmad-technical-writing/tasks/package-for-publisher.md create mode 100644 expansion-packs/bmad-technical-writing/tasks/prepare-meap-chapter.md create mode 100644 expansion-packs/bmad-technical-writing/tasks/self-publish-prep.md create mode 100644 expansion-packs/bmad-technical-writing/tasks/setup-code-repository.md create mode 100644 expansion-packs/bmad-technical-writing/tasks/take-screenshots.md create mode 100644 expansion-packs/bmad-technical-writing/tasks/validate-cross-references.md create mode 100644 expansion-packs/bmad-technical-writing/tasks/version-matrix-check.md create mode 100644 expansion-packs/bmad-technical-writing/templates/glossary-entry-tmpl.yaml diff --git a/expansion-packs/bmad-technical-writing/README.md b/expansion-packs/bmad-technical-writing/README.md index d1b3a998..72adca8c 100644 --- a/expansion-packs/bmad-technical-writing/README.md +++ b/expansion-packs/bmad-technical-writing/README.md @@ -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) diff --git a/expansion-packs/bmad-technical-writing/agents/learning-path-designer.md b/expansion-packs/bmad-technical-writing/agents/learning-path-designer.md new file mode 100644 index 00000000..b8e5c427 --- /dev/null +++ b/expansion-packs/bmad-technical-writing/agents/learning-path-designer.md @@ -0,0 +1,104 @@ + + +# 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. diff --git a/expansion-packs/bmad-technical-writing/agents/sample-code-maintainer.md b/expansion-packs/bmad-technical-writing/agents/sample-code-maintainer.md new file mode 100644 index 00000000..fef2f075 --- /dev/null +++ b/expansion-packs/bmad-technical-writing/agents/sample-code-maintainer.md @@ -0,0 +1,102 @@ + + +# 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. diff --git a/expansion-packs/bmad-technical-writing/agents/version-manager.md b/expansion-packs/bmad-technical-writing/agents/version-manager.md new file mode 100644 index 00000000..0a1e46e4 --- /dev/null +++ b/expansion-packs/bmad-technical-writing/agents/version-manager.md @@ -0,0 +1,100 @@ + + +# 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. diff --git a/expansion-packs/bmad-technical-writing/checklists/book-proposal-checklist.md b/expansion-packs/bmad-technical-writing/checklists/book-proposal-checklist.md new file mode 100644 index 00000000..8ce976b4 --- /dev/null +++ b/expansion-packs/bmad-technical-writing/checklists/book-proposal-checklist.md @@ -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 diff --git a/expansion-packs/bmad-technical-writing/checklists/citation-accuracy-checklist.md b/expansion-packs/bmad-technical-writing/checklists/citation-accuracy-checklist.md new file mode 100644 index 00000000..067f0325 --- /dev/null +++ b/expansion-packs/bmad-technical-writing/checklists/citation-accuracy-checklist.md @@ -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 diff --git a/expansion-packs/bmad-technical-writing/checklists/cross-platform-checklist.md b/expansion-packs/bmad-technical-writing/checklists/cross-platform-checklist.md new file mode 100644 index 00000000..81b0e463 --- /dev/null +++ b/expansion-packs/bmad-technical-writing/checklists/cross-platform-checklist.md @@ -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 diff --git a/expansion-packs/bmad-technical-writing/checklists/final-manuscript-checklist.md b/expansion-packs/bmad-technical-writing/checklists/final-manuscript-checklist.md new file mode 100644 index 00000000..1a169195 --- /dev/null +++ b/expansion-packs/bmad-technical-writing/checklists/final-manuscript-checklist.md @@ -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 diff --git a/expansion-packs/bmad-technical-writing/checklists/inclusive-language-checklist.md b/expansion-packs/bmad-technical-writing/checklists/inclusive-language-checklist.md new file mode 100644 index 00000000..421c7eec --- /dev/null +++ b/expansion-packs/bmad-technical-writing/checklists/inclusive-language-checklist.md @@ -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 diff --git a/expansion-packs/bmad-technical-writing/checklists/index-completeness-checklist.md b/expansion-packs/bmad-technical-writing/checklists/index-completeness-checklist.md new file mode 100644 index 00000000..7ef1250d --- /dev/null +++ b/expansion-packs/bmad-technical-writing/checklists/index-completeness-checklist.md @@ -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) diff --git a/expansion-packs/bmad-technical-writing/checklists/meap-readiness-checklist.md b/expansion-packs/bmad-technical-writing/checklists/meap-readiness-checklist.md new file mode 100644 index 00000000..4c9eab57 --- /dev/null +++ b/expansion-packs/bmad-technical-writing/checklists/meap-readiness-checklist.md @@ -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 diff --git a/expansion-packs/bmad-technical-writing/checklists/readability-checklist.md b/expansion-packs/bmad-technical-writing/checklists/readability-checklist.md new file mode 100644 index 00000000..1d3b29a3 --- /dev/null +++ b/expansion-packs/bmad-technical-writing/checklists/readability-checklist.md @@ -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 diff --git a/expansion-packs/bmad-technical-writing/checklists/repository-quality-checklist.md b/expansion-packs/bmad-technical-writing/checklists/repository-quality-checklist.md new file mode 100644 index 00000000..7340dd88 --- /dev/null +++ b/expansion-packs/bmad-technical-writing/checklists/repository-quality-checklist.md @@ -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) diff --git a/expansion-packs/bmad-technical-writing/checklists/self-publishing-standards-checklist.md b/expansion-packs/bmad-technical-writing/checklists/self-publishing-standards-checklist.md new file mode 100644 index 00000000..38a3e336 --- /dev/null +++ b/expansion-packs/bmad-technical-writing/checklists/self-publishing-standards-checklist.md @@ -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) diff --git a/expansion-packs/bmad-technical-writing/config.yaml b/expansion-packs/bmad-technical-writing/config.yaml index 50aca6b7..fec4171d 100644 --- a/expansion-packs/bmad-technical-writing/config.yaml +++ b/expansion-packs/bmad-technical-writing/config.yaml @@ -1,22 +1,31 @@ # 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 diff --git a/expansion-packs/bmad-technical-writing/tasks/create-appendix.md b/expansion-packs/bmad-technical-writing/tasks/create-appendix.md new file mode 100644 index 00000000..f55b84a9 --- /dev/null +++ b/expansion-packs/bmad-technical-writing/tasks/create-appendix.md @@ -0,0 +1,213 @@ + + +# 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 diff --git a/expansion-packs/bmad-technical-writing/tasks/create-index-entries.md b/expansion-packs/bmad-technical-writing/tasks/create-index-entries.md new file mode 100644 index 00000000..f348ab4f --- /dev/null +++ b/expansion-packs/bmad-technical-writing/tasks/create-index-entries.md @@ -0,0 +1,157 @@ + + +# 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 diff --git a/expansion-packs/bmad-technical-writing/tasks/create-preface.md b/expansion-packs/bmad-technical-writing/tasks/create-preface.md new file mode 100644 index 00000000..62bbe287 --- /dev/null +++ b/expansion-packs/bmad-technical-writing/tasks/create-preface.md @@ -0,0 +1,253 @@ + + +# 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 diff --git a/expansion-packs/bmad-technical-writing/tasks/create-solutions.md b/expansion-packs/bmad-technical-writing/tasks/create-solutions.md new file mode 100644 index 00000000..fc755d3d --- /dev/null +++ b/expansion-packs/bmad-technical-writing/tasks/create-solutions.md @@ -0,0 +1,341 @@ + + +# 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 diff --git a/expansion-packs/bmad-technical-writing/tasks/design-diagram-set.md b/expansion-packs/bmad-technical-writing/tasks/design-diagram-set.md new file mode 100644 index 00000000..45bc6ec8 --- /dev/null +++ b/expansion-packs/bmad-technical-writing/tasks/design-diagram-set.md @@ -0,0 +1,211 @@ + + +# 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 diff --git a/expansion-packs/bmad-technical-writing/tasks/design-learning-path.md b/expansion-packs/bmad-technical-writing/tasks/design-learning-path.md new file mode 100644 index 00000000..91e035c6 --- /dev/null +++ b/expansion-packs/bmad-technical-writing/tasks/design-learning-path.md @@ -0,0 +1,335 @@ + + +# 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 diff --git a/expansion-packs/bmad-technical-writing/tasks/package-for-publisher.md b/expansion-packs/bmad-technical-writing/tasks/package-for-publisher.md new file mode 100644 index 00000000..934d0569 --- /dev/null +++ b/expansion-packs/bmad-technical-writing/tasks/package-for-publisher.md @@ -0,0 +1,123 @@ + + +# 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 diff --git a/expansion-packs/bmad-technical-writing/tasks/prepare-meap-chapter.md b/expansion-packs/bmad-technical-writing/tasks/prepare-meap-chapter.md new file mode 100644 index 00000000..5b66fa40 --- /dev/null +++ b/expansion-packs/bmad-technical-writing/tasks/prepare-meap-chapter.md @@ -0,0 +1,125 @@ + + +# 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 diff --git a/expansion-packs/bmad-technical-writing/tasks/self-publish-prep.md b/expansion-packs/bmad-technical-writing/tasks/self-publish-prep.md new file mode 100644 index 00000000..ccb2ddd3 --- /dev/null +++ b/expansion-packs/bmad-technical-writing/tasks/self-publish-prep.md @@ -0,0 +1,210 @@ + + +# 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 diff --git a/expansion-packs/bmad-technical-writing/tasks/setup-code-repository.md b/expansion-packs/bmad-technical-writing/tasks/setup-code-repository.md new file mode 100644 index 00000000..fd4def7e --- /dev/null +++ b/expansion-packs/bmad-technical-writing/tasks/setup-code-repository.md @@ -0,0 +1,557 @@ + + +# 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 diff --git a/expansion-packs/bmad-technical-writing/tasks/take-screenshots.md b/expansion-packs/bmad-technical-writing/tasks/take-screenshots.md new file mode 100644 index 00000000..e89ba984 --- /dev/null +++ b/expansion-packs/bmad-technical-writing/tasks/take-screenshots.md @@ -0,0 +1,100 @@ + + +# 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 diff --git a/expansion-packs/bmad-technical-writing/tasks/validate-cross-references.md b/expansion-packs/bmad-technical-writing/tasks/validate-cross-references.md new file mode 100644 index 00000000..57a0fe57 --- /dev/null +++ b/expansion-packs/bmad-technical-writing/tasks/validate-cross-references.md @@ -0,0 +1,256 @@ + + +# 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: + +## 3.2 API Design Patterns +``` + +**HTML/ePub:** +```html +Chapter 3 + + +
...
+``` + +### 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 diff --git a/expansion-packs/bmad-technical-writing/tasks/version-matrix-check.md b/expansion-packs/bmad-technical-writing/tasks/version-matrix-check.md new file mode 100644 index 00000000..15f57833 --- /dev/null +++ b/expansion-packs/bmad-technical-writing/tasks/version-matrix-check.md @@ -0,0 +1,390 @@ + + +# 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 diff --git a/expansion-packs/bmad-technical-writing/templates/glossary-entry-tmpl.yaml b/expansion-packs/bmad-technical-writing/templates/glossary-entry-tmpl.yaml new file mode 100644 index 00000000..6ae464d2 --- /dev/null +++ b/expansion-packs/bmad-technical-writing/templates/glossary-entry-tmpl.yaml @@ -0,0 +1,111 @@ +# +--- +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).