# Write Chapter Draft --- task: id: write-chapter-draft name: Write Chapter Draft description: Develop complete chapter manuscript from outline with introduction, main content, code examples, and exercises persona_default: tutorial-architect inputs: - chapter-outline - learning-objectives - target-page-count steps: - Review chapter outline for structure and objectives - Write compelling introduction (hook, context, overview, prerequisites) - Draft main content sections (concept → tutorial → examples progression) - Create and test all code examples inline - Develop practice exercises with progressive difficulty - Write chapter summary with key takeaways - Add cross-references to other chapters and resources - Include further reading references - Verify all learning objectives are addressed - Run execute-checklist.md with chapter-completeness-checklist.md - Use template chapter-draft-tmpl.yaml with create-doc.md task output: docs/chapters/chapter-{{chapter_number}}-draft.md --- ## Purpose This task guides you through writing a complete chapter draft that transforms your chapter outline into full instructional content. The focus is on creating clear, engaging technical content that helps readers learn effectively. ## Prerequisites Before starting this task: - Chapter outline completed and reviewed - Learning objectives clearly defined - Code examples planned and identified - Access to technical-writing-standards.md knowledge base - Understanding of target audience skill level ## Workflow Steps ### 1. Review Chapter Outline Understand the complete chapter structure: - Re-read the chapter outline carefully - Review learning objectives - Check prerequisite alignment - Understand how this chapter fits in the book's progression - Note all planned code examples and exercises **Validation:** Can you explain the chapter flow without looking at the outline? ### 2. Write the Introduction Create a compelling chapter opening that hooks readers and sets expectations. **Introduction Components:** **Hook (1-2 paragraphs):** - Start with a real-world problem or relatable scenario - Make readers care about learning this content - Use questions, stories, or surprising facts - Connect to reader pain points or aspirations **Context (1-2 paragraphs):** - Explain why this topic matters - Industry relevance and use cases - How it fits in the bigger technical picture - Connection to previous chapters **Overview (1 paragraph):** - What will be covered in this chapter - High-level learning path - What readers will build or accomplish **Prerequisites:** - Previous chapters required - Assumed knowledge - Software/tools needed with versions - Estimated time commitment **Learning Objectives:** - 3-5 specific, measurable outcomes - Use action verbs (implement, analyze, create, debug) - Align with Bloom's taxonomy **Use template:** introduction-tmpl.yaml for structured guidance ### 3. Draft Main Content Sections For each major section (typically 3-5 sections per chapter): **Section Structure Pattern:** **a) Concept Introduction** - Explain the concept clearly and concisely - Use analogies or real-world comparisons where helpful - Define technical terms - Provide theoretical background without overwhelming **b) Tutorial/Walkthrough** - Step-by-step hands-on implementation - Clear, numbered steps - Imperative voice ("Create...", "Add...", "Run...") - Expected output at each step - Explain what each step accomplishes and why **c) Code Examples** - Complete, runnable code (not fragments unless explained) - Inline comments explaining key lines - Best practices demonstrated - Common mistakes highlighted and avoided - Input/output examples showing expected results **d) Section Practice** - Mini-exercises reinforcing section concepts - Quick validation of understanding - Progressive difficulty within section **Progression:** Move from foundational concepts to advanced topics within the chapter, building on what was just learned. **Use template:** tutorial-section-tmpl.yaml for hands-on sections ### 4. Create Code Examples Develop all code examples referenced in the chapter: **Code Quality Standards:** - All code must be tested and run successfully - Follow language-specific style guides - Include proper error handling - Use meaningful variable names - Add comments explaining complex logic - Specify language version compatibility **Code Presentation:** - Use proper syntax highlighting (specify language) - Show complete context (imports, setup, etc.) - Provide expected output or results - Include error examples when teaching debugging - Reference code files in repository structure **Best Practices:** - Demonstrate current industry best practices - Avoid deprecated or outdated approaches - Show security-conscious coding - Consider performance implications - Follow DRY principles in examples **Use task:** create-code-example.md for each major example **Reference:** code-quality-checklist.md and code-testing-checklist.md ### 5. Add Practice Exercises Create 4-6 end-of-chapter exercises with progressive difficulty: **Basic Exercises (2-3):** - Direct application of chapter concepts - Provide clear guidance and hints - Solutions or detailed hints included **Intermediate Exercises (1-2):** - Require combining multiple concepts - More independence required - Hints provided, full solutions optional **Challenge Exercise (1):** - Advanced application requiring creativity - Minimal guidance - Extension of chapter topics **For Each Exercise:** - Clear problem statement - Specific requirements - Estimated completion time - Difficulty indicator (⭐ ⭐⭐ ⭐⭐⭐) - Hints provided progressively - Solution approach (not full code) **Use template:** exercise-set-tmpl.yaml with create-doc.md **Reference:** exercise-difficulty-checklist.md ### 6. Write Chapter Summary Conclude with effective summary (1-2 pages): **Key Takeaways:** - Bullet list of main concepts covered - Important terms and definitions - Core skills acquired **What You Accomplished:** - Concrete deliverables from this chapter - Skills checklist readers can verify - How this builds on previous learning **Looking Ahead:** - Preview of next chapter - How upcoming content will build on this foundation - Why the next topic matters **Further Reading (Optional):** - Official documentation links - Recommended articles or resources - Community resources - Tools or libraries mentioned **Avoid:** Simply repeating content. Summarize and synthesize instead. ### 7. Add Cross-References Link to related content throughout the chapter: **Internal References:** - "See Chapter 2, Section 2.3 for database setup" - "We'll explore advanced patterns in Chapter 8" - "Review the glossary in Appendix A for term definitions" **External References:** - Official documentation (with URLs) - Standards or specifications (RFCs, PEPs, etc.) - Relevant research papers or articles - Community resources (forums, guides) **Best Practices:** - Be specific with chapter and section numbers - Test all URLs for validity - Prefer stable, official sources - Note if external content may change ### 8. Include Further Reading Provide curated resources for deeper learning: **Official Sources:** - Language documentation - Framework guides - API references - Release notes for features used **Community Resources:** - Well-regarded tutorials - Video explanations - Community forums or discussion - GitHub repositories **Quality Over Quantity:** - 5-8 truly helpful resources beats 20 mediocre ones - Annotate each resource with what it provides - Organize by topic or learning path ### 9. Verify Learning Objectives Addressed Ensure all promised learning outcomes are covered: **For Each Learning Objective:** - Where in the chapter is this taught? - Are there examples demonstrating this skill? - Can readers practice this skill in exercises? - Is there clear evidence of skill achievement? **Self-Check:** - Read each objective - Find the section(s) teaching it - Verify hands-on practice exists - Confirm assessment opportunity (exercise/quiz) **If objective not adequately covered:** Add content or revise objective. ### 10. Review Against Chapter Completeness Checklist Final quality check before review: **Run:** execute-checklist.md with chapter-completeness-checklist.md **Checklist Includes:** - All sections from outline present - Learning objectives fully addressed - Code examples tested and working - Exercises appropriate difficulty - Cross-references valid - Length appropriate (15-30 pages typical) - Consistent terminology - Voice and style consistent **Fix any issues found** before marking draft complete. ## Output The completed chapter draft should be: - **Format:** Markdown (.md file) - **Location:** docs/chapters/chapter-{{chapter_number}}-draft.md - **Code Examples:** In separate repository folder with clear organization - **Length:** Typically 15-30 pages (adjust based on topic complexity) - **Status:** Ready for technical review ## Quality Standards A high-quality chapter draft: ✓ Hooks readers with compelling introduction ✓ Explains concepts clearly with helpful analogies ✓ Provides hands-on tutorials with clear steps ✓ Includes tested, working code examples ✓ Offers exercises at appropriate difficulty ✓ Summarizes key takeaways effectively ✓ Addresses all learning objectives ✓ Maintains consistent voice and style ✓ References sources appropriately ✓ Follows technical writing best practices ## Common Pitfalls Avoid these common mistakes: ❌ **Too much theory, not enough practice** - Balance concepts with hands-on work ❌ **Code examples that don't run** - Test everything before including ❌ **Unclear instructions** - Be specific; use numbered steps ❌ **Assuming too much knowledge** - State prerequisites explicitly ❌ **Inconsistent terminology** - Use terms consistently throughout ❌ **No connection between sections** - Add transitions and explain flow ❌ **Exercises too easy or too hard** - Progressive difficulty is key ❌ **Missing the "why"** - Always explain why things matter ## Next Steps After completing the chapter draft: 1. Save and commit draft to repository 2. Proceed to technical-review-chapter.md task 3. Technical reviewer will assess accuracy and quality 4. Revise based on technical review feedback 5. Proceed to copy-edit-chapter.md for editorial polish 6. Address copy edit feedback 7. Mark chapter complete and ready for publication review ## Related Resources - Template: chapter-draft-tmpl.yaml - Template: introduction-tmpl.yaml - Template: tutorial-section-tmpl.yaml - Template: exercise-set-tmpl.yaml - Task: create-code-example.md - Task: create-doc.md - Checklist: chapter-completeness-checklist.md - Knowledge Base: technical-writing-standards.md