Chapter Development
This chapter covers the complete process of developing a single chapter from initial concept to finished content. The techniques here combine the prompting strategies and pushback methods from previous chapters into a practical workflow.
The Chapter Development Pipeline
Each chapter moves through five stages:
- Scoping — defining what the chapter covers and doesn't cover
- Outlining — structuring the content hierarchically
- Drafting — generating initial prose and code
- Refining — iterative improvement through pushback
- Integrating — connecting with the rest of the book
Stage 1: Scoping
Before writing, answer these questions:
What problem does this chapter solve for the reader? The answer becomes your chapter's purpose. Every section should serve this purpose.
What does the reader know before this chapter? List specific concepts, tools, and terminology. This defines your starting point.
What can the reader do after this chapter? List concrete capabilities. This defines your ending point.
What belongs in other chapters? Explicitly list adjacent topics that should be covered elsewhere. This prevents scope creep.
Document your answers. They guide all subsequent decisions.
Scoping Example
## Chapter 5: Authentication Scope
**Purpose:** Enable readers to implement secure user authentication
**Prerequisites (reader already knows):**
- HTTP request/response cycle
- Basic database operations
- Session concepts
**Outcomes (reader can do after):**
- Implement password-based login
- Generate and validate JWTs
- Protect routes requiring authentication
- Handle authentication errors
**Excluded (covered elsewhere):**
- OAuth2/social login (chapter 8)
- Authorization/permissions (chapter 6)
- Password reset flows (chapter 9)
- Session storage strategies (chapter 5.5)
Stage 2: Outlining
Generate a detailed outline before prose:
Create an outline for chapter 5 on authentication.
Scope (attached above).
Requirements:
- 6-10 major sections (H2)
- 2-4 subsections per major section (H3) where appropriate
- Note where code examples should appear
- Estimate word count per section
- Total target: 4000-5000 words
Format:
## Section Name (estimated words)
- Key point 1
- Key point 2
- [Code example: description]
### Subsection if needed
- Key point
Review the outline critically:
- Does the order make sense pedagogically?
- Are there gaps between sections where readers would be confused?
- Does each section advance the chapter's purpose?
- Is any section doing too much?
Revise the outline until the structure is solid:
Revise the outline with these changes:
1. Move "Token Storage" before "Token Validation" - readers need
to understand storage before validation makes sense
2. Split "Error Handling" into "Authentication Errors" and
"Token Errors" - these have different handling strategies
3. Add a section on testing authentication
4. Remove the OAuth mention - that's chapter 8
Approve the outline before proceeding to drafting.
Stage 3: Drafting
With an approved outline, generate the initial draft:
Write chapter 5 following the approved outline.
Reference files for style consistency:
- Read src/chapter-3.md for prose style
- Read src/chapter-4.md for code example format
Additional requirements:
- All code examples must be complete and runnable
- Use the project's established variable naming conventions
- End with a summary listing what was covered
For longer chapters (5000+ words), draft in sections:
Write sections 1-3 of chapter 5 following the outline.
Stop after the "Password Hashing" section.
Then:
Continue with sections 4-6 of chapter 5.
Start from "Token Generation" through "Token Validation".
Maintain consistency with sections 1-3.
Drafting in sections keeps each generation focused and prevents quality degradation in long outputs.
Stage 4: Refining
Apply the pushback techniques from the previous chapter systematically:
First pass: Comprehensiveness
Review the complete chapter draft. What topics within the
defined scope are missing or underdeveloped? List them.
Address the gaps:
Expand the section on [topic] to cover [missing aspect].
Second pass: Depth
Read each section and identify where you (as an expert) want more detail:
The section on password hashing mentions bcrypt but doesn't
explain work factors. Add:
- What work factors are
- How to choose an appropriate value
- How to adjust over time as hardware improves
Third pass: Practical concerns
Read this chapter as someone implementing this in production.
What operational concerns are missing?
- Logging (what to log, what not to log for security)
- Monitoring (what metrics matter)
- Incident response (what to do when authentication is compromised)
Fourth pass: Reader questions
What questions would a reader likely have after each section
that aren't answered? List them by section.
Address the questions that fall within scope. Add cross-references for questions answered elsewhere.
Stage 5: Integrating
Connect the chapter to the rest of the book:
Forward references:
Review this chapter for concepts that will be explained in
later chapters. Add forward references like: "We'll cover
[topic] in detail in Chapter N."
Back references:
Review this chapter for concepts explained in earlier chapters.
Where readers might need a reminder, add references like:
"As we saw in Chapter N, [brief reminder]."
Terminology consistency:
Check this chapter against the glossary in appendix B.
Flag any terms used differently or not defined.
Code consistency:
Review all code examples for consistency with examples in
chapters 3 and 4. Specifically check:
- Import statements
- Error handling patterns
- Variable naming conventions
- Comment style
Complete Example: Developing a Chapter
This example shows the full pipeline for a chapter on "Error Handling."
Scoping Session
I'm developing chapter 6 on error handling. Help me define the scope.
The book covers [web framework] for [language].
Readers have completed chapters on routing, request handling, and responses.
Chapter 7 will cover logging and monitoring.
Questions to answer:
1. What error handling topics must this chapter cover?
2. What's adjacent but belongs elsewhere?
3. What can readers do after completing this chapter?
Claude Code responds with a proposed scope. You refine it:
Good scope, with these adjustments:
- Add "error propagation across service boundaries" - readers
will hit this in real projects
- Remove "panic handling" - this is [language]-specific and
covered in the language fundamentals chapter
- Clarify: readers should be able to implement a consistent
error handling strategy, not just handle individual errors
Outlining Session
Create an outline for chapter 6 based on our defined scope.
[Include finalized scope]
Target length: 4500 words
Include at least 5 code examples
Review and revise:
The outline needs restructuring:
1. Start with "Why Error Handling Strategy Matters" - currently
section 4, should be section 1 to motivate the rest
2. "Error Types" should come before "Creating Custom Errors" -
readers need to understand the taxonomy first
3. Add a section showing a complete request with error handling
at each layer - readers need to see how the pieces fit together
Drafting Session
Write chapter 6 following the approved outline.
Read chapter-4.md and chapter-5.md for style consistency.
Additional requirements:
- Code examples should show error handling in context, not isolated
- Include "what not to do" examples alongside correct patterns
- Use realistic error scenarios (network failures, validation, auth)
Refining Sessions
Review the complete draft. As someone implementing a production
service, what error handling concerns are missing?
The "Error Responses" section shows the error format but not
how to ensure consistent formatting across all endpoints.
Add middleware/interceptor patterns for consistent error formatting.
What happens when errors occur in background jobs vs. HTTP
requests? Address the different handling requirements.
The section on logging errors says "log appropriately" but
doesn't specify what context to include. Expand with:
- Required context for debugging
- What NOT to log (PII, credentials)
- Correlation IDs for request tracing
Integration Session
The chapter is content-complete. Now integrate with the book:
1. Add forward reference to chapter 7 for logging details
2. Add back reference to chapter 4's request context pattern
3. Ensure error format matches examples in chapter 5
4. Check all terminology against appendix glossary
Tracking Progress
For long writing sessions, maintain a chapter status document:
## Chapter 6: Error Handling - Status
### Scope: APPROVED
### Outline: APPROVED (revision 2)
### Sections Status:
1. Why Error Handling Strategy Matters - REFINED (2 passes)
2. Error Types and Categories - REFINED (1 pass)
3. Creating Custom Error Types - DRAFTED (needs depth)
4. Error Propagation - DRAFTED (needs code example)
5. Error Responses - REFINED (2 passes)
6. Error Recovery Patterns - NOT STARTED
7. Complete Request Example - NOT STARTED
8. Summary - NOT STARTED
### Integration: NOT STARTED
### Open Questions:
- Should retry logic go here or in chapter 9?
- Need to verify error codes against API spec
Update this document as you progress through the chapter.
Next Steps
Chapters become excellent through careful attention to code examples. The next chapter covers techniques for creating, formatting, and validating technical code examples within your documentation.