Step 6: Chapter Writing
Goal
Transform topic analysis documents into polished chapters. This is the main execution phase where the guide content is created.
Inputs Required
| Input | Source | Purpose |
|-------|--------|---------|
| Topic analysis | topic_analysis/ch[X]_*.md | Content and structure |
| Document spec | document_spec.md | Style and format |
| Revised syllabus | syllabus_revised.md | Section structure |
| Introduction | guide_draft/00_introduction.md | Tone reference |
Chapter Structure Template
Every chapter follows this structure:
# Chapter [N]: [Title]
[Opening hook - 1-2 sentences that make reader want to continue]
[Brief chapter preview - what reader will learn]
---
## [Section N.1]: [Section Title]
[Section content]
---
## [Section N.2]: [Section Title]
[Section content]
---
## [Section N.3]: [Section Title]
[Section content]
---
## Chapter Summary
**Key Takeaways:**
- [Takeaway 1]
- [Takeaway 2]
- [Takeaway 3]
**Try This:**
[One specific action reader can take immediately]
---
*Next: [Brief teaser for next chapter]*
Process Per Chapter
6.1 Pre-Writing Setup
Before writing each chapter:
## Pre-Writing Checklist
- [ ] Read topic analysis file completely
- [ ] Review document spec (voice, tone, formatting)
- [ ] Check previous chapter ending (for continuity)
- [ ] Note required visuals/examples
- [ ] Set target word count: [X] words
- [ ] Estimate time: [X] minutes
6.2 Opening Hook
Each chapter needs a hook:
Hook Types for Chapters:
| Type | Example | Best For | |------|---------|----------| | Problem | "You've probably asked AI to 'fix the bug' and gotten garbage." | Problem chapters | | Story | "Last week, a junior developer asked me..." | Example chapters | | Question | "What's the difference between a good prompt and a great one?" | Concept chapters | | Contrast | "Most people give AI more. The secret is giving less - but better." | Advanced chapters | | Callback | "In Chapter 1, we saw why context matters. Now let's build it." | Sequential chapters |
Template:
[Hook - maximum 2 sentences]
In this chapter, you'll learn:
- [Outcome 1]
- [Outcome 2]
- [Outcome 3]
6.3 Section Writing
For each section within a chapter:
Section Structure:
1. Topic sentence (what this section covers)
2. Explanation (the concept)
3. Example (concrete illustration)
4. Application (how reader uses this)
5. Transition (connection to next section)
Example Section:
## 2.1: The Five Components of Good Context
Every effective AI context includes five components. Miss one, and your results suffer.
**1. The Task** - What you want AI to do
Not just "write code" but "write a function that validates email addresses."
**2. The Constraints** - What AI must not do
"Don't use regex. Must handle international emails. Max 50 lines."
**3. The Background** - Why you need this
"Users are signing up with invalid emails. This function will run on every form submit."
**4. The Examples** - What good output looks like
"Here's a similar function we use for phone validation: [code]"
**5. The Success Criteria** - How you'll judge the result
"Should handle edge cases like: test+filter@gmail.com, name@subdomain.company.co.uk"
When you provide all five, AI has everything it needs. Let's look at each in detail...
6.4 Example Writing
Examples are critical. Each chapter needs 2-4 solid examples.
Example Format:
### Example: [Descriptive Title]
**Scenario:** [What situation this addresses]
> ❌ **Without Context:**
> "[Bad prompt/approach]"
>
> **Result:** [What goes wrong]
> ✅ **With Context:**
> "[Good prompt/approach]"
>
> **Result:** [What works and why]
**Why This Works:**
[1-2 sentences explaining the principle demonstrated]
Example Requirements:
- Mix technical and non-technical examples
- Use realistic scenarios (not toy problems)
- Show actual prompts, not descriptions of prompts
- Include the result, not just the input
6.5 Visual Elements
Insert visuals where noted in topic analysis:
Diagram Insertion:
[Diagram: Prompt vs Context Components]
┌─────────────────────────────────────┐ │ YOUR INPUT │ ├─────────────────────────────────────┤ │ PROMPT (10%) │ CONTEXT (90%) │ │ "What to do" │ "Everything │ │ │ else" │ └─────────────────────────────────────┘
The diagram above shows...
Table Insertion:
| Component | What It Is | Example |
|-----------|------------|---------|
| Task | The action | "Write a function" |
| Constraints | Limitations | "No regex" |
| Background | Why you need it | "For signup form" |
| Examples | Reference | "[code block]" |
| Criteria | Success measure | "Handles edge cases" |
6.6 Citation Integration
Weave citations naturally:
Good:
Research supports this approach. A 2025 study by Chroma found that
AI performance actually degrades as context length increases beyond
the relevant information. More isn't better—relevant is better.
As Andrej Karpathy puts it:
> "Context engineering is the delicate art and science of filling
> the context window with just the right information for the next step."
This means...
Bad:
According to Chroma Research (2025), AI performance degrades with
irrelevant context [1]. Karpathy (2025) agrees [2]. Therefore...
6.7 Chapter Summary
End each chapter strong:
## Chapter Summary
You've learned how context differs from prompting and why it matters.
**Key Takeaways:**
1. [Most important point - actionable]
2. [Second most important - memorable]
3. [Third point - ties to bigger picture]
**Try This Now:**
Take your last failed AI prompt. Apply the five-component framework.
Add what was missing. Try again. Notice the difference.
---
*In the next chapter, we'll tackle the most common mistakes people make
with context—and how to avoid them.*
Writing Workflow
For Each Chapter:
1. READ topic analysis (10 min)
↓
2. OUTLINE chapter structure (10 min)
- List sections
- Note examples needed
- Note visuals needed
↓
3. WRITE opening hook (5 min)
↓
4. WRITE each section (15-20 min each)
- Section 1
- Section 2
- Section 3
- ...
↓
5. CREATE/INSERT visuals (10-15 min)
↓
6. WRITE chapter summary (10 min)
↓
7. FIRST EDIT (15-20 min)
- Cut fluff
- Strengthen weak sentences
- Check flow
↓
8. READ ALOUD (10 min)
- Find awkward phrases
- Check rhythm
↓
9. FINAL POLISH (10 min)
- Format check
- Citation check
- Consistency check
Chapter Writing Order
Follow dependencies from syllabus:
## Recommended Order
1. **Chapter 1** (Foundations)
- Sets tone for entire guide
- Introduces core concepts
- Reference for later chapters
2. **Chapters 2-3** (Core concepts)
- Build on Chapter 1
- Most referenced by later chapters
3. **Chapters 4-5** (Practice)
- Apply concepts from 1-3
- Can be written in parallel
4. **Final chapters** (Advanced/Team)
- Depend on all previous
- Write last
5. **Appendix** (Quick Reference)
- Extract from written chapters
- Write after all chapters done
Quality Checklist Per Chapter
| Criterion | Check | |-----------|-------| | Opens with hook (not "In this chapter...") | ☐ | | Clear section structure | ☐ | | At least 2 concrete examples | ☐ | | Examples include both tech and non-tech | ☐ | | Visuals included where planned | ☐ | | Citations properly integrated | ☐ | | Chapter summary present | ☐ | | "Try This" action included | ☐ | | Transition to next chapter | ☐ | | Word count within target (±20%) | ☐ | | Matches document spec style | ☐ |
Common Pitfalls
- Starting with "In this chapter..." - Boring. Start with hook.
- Examples too abstract - Use real prompts, real scenarios.
- Wall of text - Break up with headers, lists, examples.
- Forgetting visuals - Check topic analysis for required visuals.
- Orphan concepts - Every concept introduced must be explained.
- Weak endings - Summary and next-chapter teaser matter.
- Inconsistent depth - Same level of detail throughout.
- Losing voice - Re-read introduction to maintain tone.
Time Estimates Per Chapter
| Chapter Complexity | Estimated Time | |-------------------|----------------| | Foundation (new concepts) | 2-3 hours | | Practice (examples-heavy) | 2-2.5 hours | | Advanced (building on previous) | 1.5-2 hours | | Appendix (extraction/formatting) | 1-1.5 hours |
Total for 7-8 chapters: 12-20 hours
Output
For each chapter, create:
guide_draft/
├── 01_part1_ch1_[name].md
├── 02_part1_ch2_[name].md
├── 03_part2_ch3_[name].md
├── ...
└── XX_appendix.md
Progress Tracking
Update as you complete chapters:
## Chapter Status
| Chapter | Status | Word Count | Review |
|---------|--------|------------|--------|
| Ch 1 | ✅ Complete | 4,200 | Passed |
| Ch 2 | ✅ Complete | 3,800 | Passed |
| Ch 3 | 🔄 In Progress | 2,100 | - |
| Ch 4 | ⏳ Not Started | - | - |
| ... | ... | ... | ... |
Next Step
→ Once all chapters are complete, proceed to 07_completeness_review.md