Introduction

Technical documentation has always been a bottleneck in software development. Developer Relations professionals understand this tension intimately: the need for comprehensive, accurate, up-to-date documentation versus the reality of limited time, shifting priorities, and the constant evolution of the technologies being documented.

This book presents a methodology for creating technical books and documentation using Claude Code as a collaborative authoring tool. The approach described here is not about generating content and publishing it unchanged. It is about establishing a structured dialogue between human expertise and AI capability to produce documentation that exceeds what either could create alone.

Why AI-Assisted Technical Writing

The case for AI-assisted technical writing rests on three observations:

Scale without sacrifice. Traditional technical writing forces a tradeoff between depth and breadth. A single author can write comprehensively about a narrow topic or superficially about a broad one. AI assistance shifts this constraint. Claude Code can maintain consistency across hundreds of pages while you focus on accuracy and strategic direction.

Structural consistency. Technical books require rigorous structural patterns: consistent heading hierarchies, uniform code example formatting, standardized terminology. Maintaining these patterns across a long document taxes human attention. Claude Code excels at applying patterns consistently once they are established.

Iteration velocity. The difference between adequate documentation and excellent documentation is iteration. Each pass through a chapter reveals gaps, ambiguities, and opportunities for clarification. AI assistance compresses the iteration cycle from days to hours.

What This Book Covers

This book documents a complete workflow for creating technical books using Claude Code:

• Project setup and structure — establishing the foundation for a maintainable book project
• Writing strategy — crafting prompts that produce usable first drafts
• Iterative refinement — the critical process of questioning, expanding, and improving AI-generated content
• Code example integration — ensuring technical accuracy in all code samples
• Quality control — systematic approaches to comprehensive coverage
• Publishing — building and deploying the finished product

The Central Thesis

The methodology in this book centers on a single principle: the quality of AI-assisted writing is determined by the quality of your feedback, not the quality of your initial prompt.

A well-crafted prompt produces a reasonable first draft. That draft becomes excellent documentation through iterative refinement — asking "is this comprehensive enough?", "what edge cases are missing?", "can you provide more detail on X?", and "what would a reader struggle with here?"

This iterative process is not a workaround for AI limitations. It is the fundamental mechanism for producing high-quality technical content. The same process applies to human-written documentation; AI assistance simply makes each iteration cycle faster.

Who Should Read This Book

This book is written for Developer Relations professionals who:

• Create technical documentation, tutorials, and guides as part of their work
• Want to increase their documentation output without sacrificing quality
• Are comfortable with command-line tools and version control
• Have access to Claude Code (Anthropic's CLI tool for Claude)

The examples use mdBook for final output, but the principles apply to any documentation format.

How to Use This Book

Read chapters 1-4 sequentially to understand the foundational concepts. Chapters 5-8 can be referenced as needed during active book projects. Chapters 9-11 provide reference material for specific situations.

Each chapter includes practical examples drawn from real documentation projects. The code examples are complete and tested. The prompting examples reflect actual interactions with Claude Code.

This book was itself written using the methodology it describes. The meta-circularity is intentional: the techniques work because they are being demonstrated in their own documentation.

Setup and Configuration

This chapter covers the technical prerequisites for using Claude Code as a book authoring tool. The setup process involves installing Claude Code, configuring mdBook, and establishing a project structure optimized for iterative writing.

Prerequisites

Before beginning, ensure you have:

• Node.js 18+ or access to Claude Code through Anthropic's distribution
• Rust and Cargo (for mdBook installation)
• Git (for version control)
• A text editor with Markdown support

Installing Claude Code

Claude Code is Anthropic's command-line interface for Claude. Install it following the official documentation at claude.ai/claude-code.

Verify the installation:

claude --version

Claude Code operates in your terminal with full access to your filesystem, enabling it to read existing content, create new files, and modify drafts directly.

Installing mdBook

mdBook is a command-line tool for creating books from Markdown files. Install it via Cargo:

cargo install mdbook

Verify the installation:

mdbook --version

For additional functionality, consider these plugins:

# Syntax highlighting for more languages
cargo install mdbook-mermaid

# Table of contents in each page
cargo install mdbook-toc

# Search functionality enhancement
cargo install mdbook-pagetoc

Project Initialization

Create a new book project:

mdbook init my-technical-book
cd my-technical-book

This creates the basic structure:

my-technical-book/
├── book.toml
└── src/
    ├── SUMMARY.md
    └── chapter_1.md

Configuration

The book.toml file controls your book's metadata and build settings. A production-ready configuration:

[book]
authors = ["Your Name"]
language = "en"
multilingual = false
src = "src"
title = "Your Book Title"
description = "A concise description for metadata and SEO"

[build]
build-dir = "book"
create-missing = false

[output.html]
default-theme = "light"
preferred-dark-theme = "ayu"
git-repository-url = "https://github.com/yourorg/your-book"
edit-url-template = "https://github.com/yourorg/your-book/edit/main/{path}"

[output.html.fold]
enable = true
level = 1

[output.html.search]
enable = true
limit-results = 30
teaser-word-count = 30
use-hierarchical = true

Key settings:

• create-missing = false prevents mdBook from creating placeholder files, ensuring your SUMMARY.md remains the source of truth
• edit-url-template adds "suggest an edit" links to each page
• fold.level = 1 collapses sidebar sections by default, improving navigation for large books

Claude Code Configuration

Claude Code uses a CLAUDE.md file in your project root for persistent context. Create one tailored for book authoring:

# Project: Technical Book

This is an mdBook project for technical documentation.

## Structure
- `src/SUMMARY.md` - Table of contents (source of truth for chapter order)
- `src/*.md` - Individual chapter files
- `book.toml` - mdBook configuration

## Writing Standards
- Use ATX-style headers (# not underlines)
- Code blocks must specify language for syntax highlighting
- Keep paragraphs focused on single concepts
- Use second person ("you") for instructions
- Use present tense for descriptions

## Terminology
- "Claude Code" not "Claude" when referring to the CLI tool
- "mdBook" not "mdbook" or "Mdbook"
- Define acronyms on first use

## Chapter Template
Each chapter should include:
1. Opening paragraph stating the chapter's purpose
2. Conceptual explanation
3. Practical examples
4. Common pitfalls or considerations
5. Summary or transition to next chapter

This file persists across Claude Code sessions, maintaining consistency throughout your writing project.

Version Control Setup

Initialize git and create a .gitignore:

git init

Create .gitignore:

# Build output
book/

# Editor files
*.swp
*~
.vscode/
.idea/

# OS files
.DS_Store
Thumbs.db

Make your initial commit:

git add .
git commit -m "Initial book structure"

Development Workflow

Build and serve your book locally during development:

mdbook serve --open

This starts a local server at http://localhost:3000 with live reload. Changes to any .md file trigger an automatic rebuild.

For Claude Code sessions, keep this running in a separate terminal. You can ask Claude Code to make changes and immediately see the results in your browser.

Verifying the Setup

Test your environment by asking Claude Code to make a small change:

Add a brief placeholder paragraph to chapter_1.md explaining
that this content will be expanded.

Then verify:

1. The file was modified correctly
2. mdBook rebuilt automatically
3. The change appears in your browser

Your environment is ready for book authoring when all three steps succeed.

Next Steps

With the technical foundation in place, the next chapter covers project structure — organizing chapters, managing assets, and planning your book's architecture before writing begins.

Project Structure

A well-organized project structure is the foundation for maintainable technical documentation. This chapter covers the organization patterns that work best with Claude Code's file-based workflow.

Directory Layout

The recommended structure for a technical book:

your-book/
├── book.toml
├── CLAUDE.md
├── .gitignore
├── src/
│   ├── SUMMARY.md
│   ├── introduction.md
│   ├── part-1/
│   │   ├── chapter-1.md
│   │   ├── chapter-2.md
│   │   └── chapter-3.md
│   ├── part-2/
│   │   ├── chapter-4.md
│   │   └── chapter-5.md
│   ├── appendices/
│   │   ├── appendix-a.md
│   │   └── appendix-b.md
│   └── images/
│       ├── diagram-1.png
│       └── screenshot-1.png
├── examples/
│   ├── chapter-1/
│   │   └── complete-example.rs
│   └── chapter-4/
│       └── demo-project/
└── scripts/
    └── validate-examples.sh

The SUMMARY.md File

SUMMARY.md is the table of contents and the source of truth for your book's structure. mdBook generates navigation from this file.

# Summary

[Introduction](./introduction.md)

# Part 1: Foundations

- [Core Concepts](./part-1/chapter-1.md)
- [Architecture](./part-1/chapter-2.md)
- [Configuration](./part-1/chapter-3.md)

# Part 2: Advanced Topics

- [Performance](./part-2/chapter-4.md)
- [Scaling](./part-2/chapter-5.md)

---

[Appendix A: Reference](./appendices/appendix-a.md)
[Appendix B: Glossary](./appendices/appendix-b.md)

Key formatting rules:

• Part headers use # Part Name syntax
• Chapter links use - [Title](./path.md) syntax
• Separators (---) create visual breaks in navigation
• Unnumbered appendices omit the - prefix

File Naming Conventions

Consistent naming helps both Claude Code and human collaborators navigate the project:

Chapter files:

• Use kebab-case: getting-started.md, not GettingStarted.md
• Be descriptive: error-handling.md, not chapter-7.md
• Keep names short but meaningful: auth.md or authentication.md, not a.md

Image files:

• Include chapter context: ch3-architecture-diagram.png
• Use descriptive names: oauth-flow-sequence.png, not image1.png
• Prefer PNG for diagrams, JPG for screenshots

Code example directories:

• Mirror chapter structure: examples/chapter-3/
• Use project-appropriate names: examples/auth-demo/

Organizing Large Books

Books exceeding ten chapters benefit from part-based organization:

src/
├── SUMMARY.md
├── introduction.md
├── part-1-basics/
│   ├── installation.md
│   ├── first-project.md
│   └── core-concepts.md
├── part-2-intermediate/
│   ├── advanced-config.md
│   ├── testing.md
│   └── debugging.md
└── part-3-advanced/
    ├── performance.md
    ├── scaling.md
    └── internals.md

This structure:

• Groups related chapters for easier navigation
• Allows parallel work on different parts
• Makes the scope of each section clear to Claude Code

Managing Code Examples

Code examples require special consideration. Two patterns work well:

Inline Examples

For short examples (under 30 lines), include code directly in the Markdown:

```rust
fn main() {
    println!("Hello, world!");
}
```

External Examples

For longer examples or complete projects, store them externally and reference them:

The complete implementation is available in
[`examples/chapter-5/auth-server/`](../examples/chapter-5/auth-server/).

Here's the key function:

\`\`\`rust
{{#include ../examples/chapter-5/auth-server/src/main.rs:authenticate}}
\`\`\`

mdBook's {{#include}} directive pulls code from external files, keeping examples testable and maintainable.

Working with Claude Code

Structure your project to maximize Claude Code's effectiveness:

Keep files focused. Each chapter file should cover one coherent topic. Files exceeding 500 lines become difficult to discuss and modify in conversation.

Use clear boundaries. When asking Claude Code to modify content, reference files by name: "Update the authentication section in src/part-2/auth.md" rather than "update the authentication section."

Maintain CLAUDE.md. Document structural decisions, naming conventions, and style requirements. Claude Code reads this file at the start of each session.

Example CLAUDE.md section for structure:

## Project Structure

- Chapters are in `src/` organized by part
- Code examples go in `examples/` mirroring chapter structure
- Images go in `src/images/` with chapter prefixes
- New chapters must be added to SUMMARY.md manually

## File Naming

- Chapters: kebab-case, descriptive names
- Images: chapter-prefix-description.png
- Examples: chapter-number/project-name/

Planning Chapter Dependencies

Before writing, map chapter dependencies. A chapter that references concepts from another chapter creates a dependency:

introduction.md (no dependencies)
    ↓
installation.md (no dependencies)
    ↓
core-concepts.md (depends: installation)
    ↓
first-project.md (depends: core-concepts)
    ↓
testing.md (depends: first-project, core-concepts)

This map helps you:

• Write chapters in logical order
• Know when to add cross-references
• Identify circular dependencies early

When working with Claude Code, mention dependencies explicitly: "This chapter assumes the reader has completed the installation chapter and understands the core concepts from chapter 3."

Version Control Practices

Commit strategically during book development:

Commit complete chapters. Avoid committing half-written chapters. If a writing session ends mid-chapter, use a WIP commit or stash.

Commit after successful builds. Run mdbook build before committing to ensure no broken links or syntax errors.

Use meaningful commit messages:

git commit -m "Add authentication chapter with OAuth2 examples"
git commit -m "Expand error handling section with recovery patterns"
git commit -m "Fix broken link in chapter 3"

Branch for major changes. When restructuring or rewriting significant portions, use a feature branch:

git checkout -b rewrite-part-2
# ... make changes ...
git checkout main
git merge rewrite-part-2

Validating Structure

Before significant writing sessions, validate your structure:

# Check for broken internal links
mdbook build 2>&1 | grep -i "warning"

# Verify all SUMMARY.md entries exist
mdbook build

# Preview the full structure
mdbook serve --open

Fix structural issues before writing content. Broken links and missing files create confusion during Claude Code sessions.

Next Steps

With a solid project structure in place, the next chapter covers writing strategy — how to craft prompts that produce useful first drafts for each chapter.

Writing Strategy

The quality of AI-assisted writing depends on how you structure your requests. This chapter covers prompting strategies that produce usable first drafts, setting the stage for iterative refinement.

The Two-Phase Model

Effective AI-assisted writing follows two distinct phases:

1. Generation — producing initial content through well-structured prompts
2. Refinement — improving content through iterative feedback

This chapter focuses on generation. The next chapter covers refinement in depth. Separating these phases clarifies what each prompt needs to accomplish.

Anatomy of an Effective Writing Prompt

A prompt that produces a usable first draft includes:

• Context — what already exists, what comes before and after
• Scope — exactly what this piece of content should cover
• Audience — who will read this and what they already know
• Constraints — length, format, style requirements
• Examples — models of the desired output (when available)

Context

Claude Code can read your existing files, but you must direct its attention:

I'm writing chapter 4 of a Rust web framework guide.
Chapter 3 covered basic routing. Chapter 5 will cover middleware.
This chapter needs to cover request handling.

Read src/chapter-3.md to understand the established terminology
and style, then write chapter 4.

Providing context prevents contradictions and maintains consistency across chapters.

Scope

Explicit scope prevents both under-delivery and scope creep:

Too vague:

Write about error handling.

Too broad:

Write a comprehensive guide to error handling covering all
languages, frameworks, and paradigms.

Appropriately scoped:

Write a chapter on error handling in Rust web applications.
Cover:
- The Result type and ? operator
- Custom error types
- Converting between error types
- Returning errors from HTTP handlers
- Error logging

Do not cover: panic handling, async error propagation
(covered in chapter 8), or error handling in other languages.

Audience

Define the reader's starting point:

Audience: Backend developers with 2+ years of experience in
other languages (Python, Java, Go) who are learning Rust.

They understand: HTTP, REST APIs, JSON, basic error handling concepts
They don't know: Rust's Result type, ownership, or trait system

This calibration prevents both over-explanation of familiar concepts and under-explanation of new ones.

Constraints

Specify structural and stylistic requirements:

Constraints:
- Length: 2000-3000 words
- Format: mdBook-compatible Markdown
- Code examples: Complete, compilable Rust (no pseudocode)
- Headers: ATX style (#), max depth 3
- Voice: Second person ("you"), present tense
- Include: At least one diagram (described in text for later creation)

Examples

When available, provide examples of the desired output:

Follow the style established in chapter-2.md. Note especially:
- How code examples are introduced with a problem statement
- How each section ends with a brief summary
- The balance between explanation and code (roughly 60/40)

Prompt Templates

These templates provide starting points for common writing tasks.

New Chapter

Write chapter [N]: [Title]

Context:
- Previous chapter covered: [summary]
- Next chapter will cover: [summary]
- Read [file] for style reference

Scope - this chapter covers:
- [Topic 1]
- [Topic 2]
- [Topic 3]

Scope - explicitly excluded:
- [Topic A] (covered in chapter X)
- [Topic B] (out of scope for this book)

Audience: [description]

Requirements:
- Length: [range] words
- Include [N] code examples
- End with exercises or discussion questions

Write the complete chapter now.

Section Expansion

The current [section name] in [file] is too brief.

Current content:
[paste existing content]

Expand this section to cover:
- [Additional topic 1]
- [Additional topic 2]
- [Edge case or consideration]

Maintain the existing voice and style.
Target length: [range] words for this section.

Code Example Creation

Create a code example demonstrating [concept].

Requirements:
- Language: [language]
- Must be complete and runnable
- Include necessary imports
- Add comments explaining non-obvious parts
- Show both the problem and the solution
- Length: [range] lines

Context: This example appears in a section about [topic]
for readers who understand [prerequisites] but are learning [new concept].

Chapter Outline

Create a detailed outline for a chapter on [topic].

The chapter should:
- Fit within a [type] book aimed at [audience]
- Take approximately [N] pages when written
- Include [N] code examples
- Build from [starting concept] to [ending concept]

Provide:
- Section headings with brief descriptions
- Key points to cover in each section
- Suggested code examples with one-line descriptions
- Potential pitfalls or common confusions to address

Prompting for Different Content Types

Conceptual Explanations

Conceptual content explains why and how at an abstract level:

Explain [concept] for developers who understand [prerequisite]
but are new to [this domain].

Structure the explanation as:
1. The problem this concept solves
2. The core idea in one paragraph
3. A concrete analogy
4. How it works in practice
5. Common misconceptions

Procedural Instructions

Procedural content tells readers what to do:

Write step-by-step instructions for [task].

For each step:
- State what the reader will do
- Provide the exact command or action
- Show expected output or result
- Note what could go wrong and how to recognize it

Assume the reader has completed [prerequisites].
Use numbered steps with code blocks for commands.

Reference Material

Reference content provides lookup information:

Create a reference section documenting [API/feature/concept].

For each item include:
- Name and brief description
- Syntax or signature
- Parameters with types and descriptions
- Return value
- Example usage
- Edge cases or caveats

Format as a scannable list or table. Readers will look things up,
not read linearly.

Calibrating Expectations

First drafts from Claude Code are first drafts. Expect to iterate. A good initial prompt produces content that:

• Covers the requested scope
• Uses appropriate technical depth
• Follows the specified structure
• Requires refinement, not rewriting

If first drafts consistently miss the mark, adjust your prompts. If they require complete rewrites, you need better context or scope definition. If they need only polish and expansion, your prompts are working well.

The Outline-First Approach

For complex chapters, generate an outline before prose:

Before writing, create a detailed outline for this chapter.
Include:
- All section headings (H2 and H3)
- 2-3 bullet points of key content per section
- Placement of code examples
- Estimated word count per section

Review and adjust the outline, then:

The outline looks good with these changes:
- Move section 3 before section 2
- Expand the error handling section
- Add a troubleshooting subsection at the end

Now write the full chapter following this revised outline.

This two-step process catches structural issues before investing in prose.

Common Prompting Mistakes

Assuming context. Claude Code starts each session fresh. Always reference files to read or provide necessary background.

Over-specifying style. Detailed style requirements often conflict with each other. Provide an example file and say "match this style" instead of listing twenty rules.

Under-specifying scope. "Write about X" produces generic content. "Write about X covering specifically A, B, C for audience Y" produces targeted content.

Requesting perfection. First drafts are first drafts. Prompts requesting "perfect" or "final" content create pressure that doesn't improve output. Request "complete" content and plan to iterate.

Ignoring existing content. When expanding or revising, always include or reference the existing text. Claude Code cannot remember previous sessions.

Next Steps

Even well-prompted first drafts require refinement. The next chapter covers the art of pushback — the iterative questioning process that transforms adequate content into excellent documentation.

The Art of Pushback

This chapter addresses the most important skill in AI-assisted technical writing: the iterative process of questioning, challenging, and expanding AI-generated content. This is where generic output becomes high-quality documentation.

Why Pushback Matters

The default behavior of AI writing assistance is to produce reasonable content — content that is structurally sound, factually plausible, and approximately scoped. Reasonable content is not excellent content.

The gap between reasonable and excellent documentation is filled by pushback: systematic questioning that exposes gaps, challenges assumptions, and demands greater depth. This process works because:

1. AI systems optimize for the request given. Without pushback, they optimize for reasonable completion. With pushback, they optimize for comprehensive coverage.

2. First responses are necessarily general. Specific, detailed content requires specific, detailed questions.

3. Human expertise identifies what's missing. You know your audience and your domain. AI knows patterns and structures. Pushback combines both.

The Pushback Vocabulary

Effective pushback uses specific language patterns. These are not magic incantations — they are precise questions that direct attention to specific gaps.

Comprehensiveness Questions

Is this comprehensive enough for someone who needs to actually
implement this in production?

What topics within [subject] did you not cover that a practitioner
would need to know?

If I were debugging a problem with this implementation, what
information is missing from this chapter?

What questions would a reader have after finishing this section
that aren't answered?

These questions reveal scope gaps — topics that fall within the chapter's domain but weren't included in the first draft.

Depth Questions

Can you go deeper on [specific section]? A senior developer
would want to understand the underlying mechanism, not just
the API.

The section on [topic] explains what to do but not why.
Add the reasoning behind each recommendation.

This describes the happy path. What about error cases, edge
cases, and failure modes?

A reader might ask "but what if X?" — address that scenario.

Depth questions expand existing content rather than adding new topics.

Specificity Questions

The advice in [section] is too general. Provide specific,
concrete examples.

Replace "you should consider" with specific recommendations
backed by reasoning.

Instead of "this can cause problems," explain exactly what
problems and under what conditions.

Show a real-world scenario where this applies, not an abstract description.

Specificity questions transform vague guidance into actionable content.

Challenge Questions

Are there cases where this recommendation doesn't apply?
Document the exceptions.

What's the argument against this approach? Present the tradeoffs fairly.

Is this actually best practice, or is it common practice?
What do experts in this area disagree about?

What's the failure mode of following this advice incorrectly?

Challenge questions prevent oversimplification and build reader trust.

The Pushback Loop

Effective refinement follows a consistent pattern:

[Initial Generation]
        ↓
[Your Review: Identify the weakest section]
        ↓
[Pushback Question targeting that section]
        ↓
[Claude Code Expands/Revises]
        ↓
[Your Review: Is this section now adequate?]
        ↓
   [No] → Return to Pushback
   [Yes] → Move to next weakest section
        ↓
[All sections adequate?]
        ↓
   [No] → Continue loop
   [Yes] → Final polish pass

Iterate section by section rather than attempting to fix everything at once. Each iteration should focus on one specific improvement.

Example: Before and After Pushback

Initial Draft

Error Handling

When errors occur, you should handle them appropriately. Use try-catch blocks to catch exceptions and provide meaningful error messages to users. Log errors for debugging purposes. Consider using error tracking services in production.

Pushback 1: Comprehensiveness

This error handling section is too brief. It needs to cover:
- Different error types and how to distinguish them
- Error propagation strategies
- User-facing vs. internal errors
- Structured error formats

Expand this section with these topics.

After Pushback 1

Error Handling

Errors in this system fall into three categories: validation errors (invalid user input), operational errors (failed network calls, database timeouts), and programming errors (null references, type mismatches). Each category requires different handling strategies.

Validation Errors should return immediately to the user with specific feedback about what was invalid and how to correct it. Never log validation errors as they represent normal operation.

Operational Errors may be retryable. Implement exponential backoff for transient failures. For permanent failures, provide the user with a clear message and next steps. Log all operational errors with context for debugging.

Programming Errors indicate bugs and should never reach users in production. Log with full stack traces and fail fast during development. In production, return a generic error message and alert the development team.

[continued...]

Pushback 2: Specificity

The operational errors section mentions exponential backoff but
doesn't show how to implement it. Add a code example showing
the retry pattern with configurable backoff.

Pushback 3: Challenge

You recommend failing fast for programming errors during development.
What about integration tests that intentionally trigger error paths?
Address how to test error handling without the fail-fast behavior
blocking the tests.

Each pushback iteration improves a specific aspect of the content.

Recognizing When to Push Back

Not all content needs the same level of scrutiny. Push back more aggressively on:

• Core concepts that readers must understand correctly
• Procedures that readers will follow exactly
• Recommendations that influence real decisions
• Security-related content where errors have consequences

Push back less on:

• Introductory material that orients readers
• Reference sections that readers scan, not study
• Transition paragraphs between major sections

Allocate your iteration time to the sections that matter most.

The "What Else" Technique

After apparent completion, always ask:

What else should be covered in this [chapter/section] that we
haven't addressed? List topics, don't write them yet.

This generates a punch list of potential additions. Review the list and decide which items warrant inclusion:

From your list, add coverage of items 2 and 4.
Items 1 and 3 are out of scope for this chapter.
Item 5 is covered in chapter 7 — add a cross-reference instead.

The "what else" technique catches gaps that neither you nor Claude Code initially considered.

The Reader Perspective Technique

Adopt a specific reader persona and question the content from their perspective:

Read this chapter as a junior developer six months into their
first job. What would confuse them? What would they need
explained more carefully?

Read this as a senior architect evaluating whether to adopt
this technology. What technical details would they want that
are missing?

Read this as someone debugging a production issue at 2 AM.
What quick-reference information should be easier to find?

Different reader perspectives reveal different gaps.

When to Stop Iterating

Iteration has diminishing returns. Stop when:

• Pushback yields marginal improvements. If additional questions produce minor rephrasing rather than substantive additions, the section is sufficiently developed.

• Content exceeds necessary scope. If pushback suggestions expand beyond what the audience needs, you've reached appropriate depth.

• You're polishing, not improving. If changes are stylistic rather than substantive, move to final editing.

Perfect is the enemy of shipped. Excellent documentation that exists beats perfect documentation that doesn't.

Pushback Patterns to Avoid

Vague dissatisfaction. "This doesn't feel right" gives no direction. Identify specifically what's missing or wrong.

Infinite expansion. Every topic can be explored more deeply. Define "enough" for your audience and stop there.

Conflicting requests. Asking for both brevity and comprehensiveness in the same pushback creates confusion. Choose one goal per iteration.

Style bikeshedding. Spending iteration cycles on word choice and phrasing is better left for final editing. Use pushback for content, not polish.

Integrating Pushback into Your Workflow

A practical writing session structure:

1. Generation (20%) — Create initial content with a well-structured prompt
2. Pushback (60%) — Iterate through 3-5 rounds of targeted questions
3. Polish (20%) — Final editing for style, flow, and consistency

The majority of time should be spent on pushback. This ratio produces better results than spending more time on initial prompts or final editing.

Next Steps

With pushback skills established, the next chapter covers the practical aspects of developing individual chapters from outline to completion.

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:

1. Scoping — defining what the chapter covers and doesn't cover
2. Outlining — structuring the content hierarchically
3. Drafting — generating initial prose and code
4. Refining — iterative improvement through pushback
5. 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.

Code Examples

Code examples are the core of technical documentation. Readers trust your prose because your code works. This chapter covers creating, formatting, and maintaining code examples that are accurate, instructive, and maintainable.

Principles of Good Code Examples

Complete over clever. A reader should be able to copy an example and run it. Include imports, setup, and necessary context. An elegant one-liner that requires invisible context is less useful than a verbose example that works.

Realistic over minimal. Examples should resemble real code readers will write. Use realistic variable names, realistic data, and realistic error handling. Minimal examples teach syntax; realistic examples teach practice.

Focused over comprehensive. Each example should illustrate one concept. Avoid combining multiple new ideas in a single example. If an example requires understanding A, B, and C, ensure A and B were introduced in previous examples.

Consistent over varied. Use the same patterns throughout the book. If chapter 3 uses result as a variable name for operation results, chapter 7 should too. Variation confuses readers who are pattern-matching.

Code Block Formatting

mdBook uses standard Markdown fenced code blocks with language identifiers:

```rust
fn main() {
    println!("Hello, world!");
}
```

Always specify the language. This enables syntax highlighting and signals the technology to readers.

Supported Language Identifiers

Common identifiers:

For configuration or output that isn't a programming language, use text or omit the identifier.

Line Highlighting

mdBook supports line highlighting to draw attention to specific parts:

```rust,hl_lines=3 4
fn main() {
    let name = "World";
    // These lines are highlighted
    println!("Hello, {}!", name);
}
```

Use highlighting to focus attention on new concepts within familiar boilerplate.

Hiding Lines

Hide setup code that distracts from the lesson:

```rust
# fn main() {
let x = 5;
println!("{}", x);
# }
```

Lines starting with # are hidden in the output but included in compilation. This keeps examples focused while remaining complete.

Prompting for Code Examples

When requesting code examples from Claude Code, be specific:

Weak prompt:

Show how to handle errors.

Strong prompt:

Create a code example showing HTTP error handling in [framework].

Requirements:
- Complete, runnable example
- Include imports
- Handle both client errors (4xx) and server errors (5xx)
- Show the custom error type definition
- Include a handler function that returns these errors
- Use realistic error messages

Context: This follows an example showing basic request handling.
The reader hasn't seen error handling yet.

Requesting Incremental Examples

For complex topics, request a series of examples that build on each other:

Create a progression of 4 code examples teaching async/await:

Example 1: Single async function call
- Simplest possible async operation
- Show the await point explicitly

Example 2: Sequential async calls
- Two operations that must happen in order
- Demonstrate value passing between awaits

Example 3: Concurrent async calls
- Two operations that can run simultaneously
- Show the concurrency primitive used

Example 4: Error handling in async code
- Async operation that can fail
- Proper error propagation

Each example should be complete and runnable.
Each should build on concepts from the previous example.

Code Example Types

Conceptual Examples

Illustrate a concept in isolation:

#![allow(unused)]
fn main() {
// Ownership moves when assigned
let s1 = String::from("hello");
let s2 = s1;  // s1 is no longer valid

// This would fail to compile:
// println!("{}", s1);  // error: value borrowed after move
}

Conceptual examples can be short. Their purpose is understanding, not replication.

Procedural Examples

Show how to accomplish a task:

use std::fs::File;
use std::io::{self, BufRead};
use std::path::Path;

fn read_lines<P>(filename: P) -> io::Result<Vec<String>>
where
    P: AsRef<Path>,
{
    let file = File::open(filename)?;
    let reader = io::BufReader::new(file);
    reader.lines().collect()
}

fn main() -> io::Result<()> {
    let lines = read_lines("input.txt")?;
    for line in lines {
        println!("{}", line);
    }
    Ok(())
}

Procedural examples should be complete and directly usable.

Anti-Pattern Examples

Show what not to do:

#![allow(unused)]
fn main() {
// DON'T: This creates a race condition
let counter = Rc::new(RefCell::new(0));
let c1 = counter.clone();
let c2 = counter.clone();

thread::spawn(move || {
    *c1.borrow_mut() += 1;  // Not thread-safe!
});

thread::spawn(move || {
    *c2.borrow_mut() += 1;  // Not thread-safe!
});
}

Always label anti-patterns clearly. Follow with the correct approach:

#![allow(unused)]
fn main() {
// DO: Use Arc and Mutex for thread-safe shared state
let counter = Arc::new(Mutex::new(0));
let c1 = counter.clone();
let c2 = counter.clone();

thread::spawn(move || {
    let mut num = c1.lock().unwrap();
    *num += 1;
});

thread::spawn(move || {
    let mut num = c2.lock().unwrap();
    *num += 1;
});
}

Before/After Examples

Show refactoring improvements:

Before:

#![allow(unused)]
fn main() {
fn process(data: Option<String>) -> String {
    if data.is_some() {
        let s = data.unwrap();
        if s.len() > 0 {
            s.to_uppercase()
        } else {
            "empty".to_string()
        }
    } else {
        "none".to_string()
    }
}
}

After:

#![allow(unused)]
fn main() {
fn process(data: Option<String>) -> String {
    match data {
        Some(s) if !s.is_empty() => s.to_uppercase(),
        Some(_) => "empty".to_string(),
        None => "none".to_string(),
    }
}
}

Before/after pairs make improvements concrete and memorable.

External Code Inclusion

For longer examples, store code in separate files and include it:

```rust
{{#include ../examples/ch05/complete_server.rs}}
```

The {{#include path}} directive pulls the entire file into the code block.

Including Specific Sections

Use anchor comments to include portions:

In complete_server.rs:

fn main() {
    // ANCHOR: setup
    let config = Config::load();
    let db = Database::connect(&config.database_url);
    // ANCHOR_END: setup

    // ANCHOR: server
    let server = Server::new(config.port);
    server.run(db);
    // ANCHOR_END: server
}

In your markdown, reference anchors with {{#include path:anchor}}:

First, set up the configuration:

```rust
{{#include ../examples/ch05/complete_server.rs:setup}}
```

Then start the server:

```rust
{{#include ../examples/ch05/complete_server.rs:server}}
```

This keeps examples maintainable while showing only relevant portions.

Validating Code Examples

Code examples must work. Establish a validation process:

Inline Validation

For short examples, test manually during review:

I've written a code example for error handling. Before I include
it in the chapter, verify it compiles and runs correctly.

[paste example]

If there are issues, fix them and explain what was wrong.

Automated Validation

For books with many examples, create a validation script:

#!/bin/bash
# scripts/validate-examples.sh

set -e

echo "Validating Rust examples..."
for dir in examples/*/; do
    if [ -f "$dir/Cargo.toml" ]; then
        echo "Checking $dir"
        (cd "$dir" && cargo check)
    fi
done

echo "All examples valid!"

Run validation before committing and as part of CI.

Testing Examples

Where possible, add tests to example code:

#![allow(unused)]
fn main() {
fn add(a: i32, b: i32) -> i32 {
    a + b
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_add() {
        assert_eq!(add(2, 2), 4);
        assert_eq!(add(-1, 1), 0);
    }
}
}

Tests prove examples work and catch regressions when updating.

Common Code Example Problems

Missing Imports

Problem: Examples assume imports exist.

// Won't compile alone
fn main() {
    let file = File::open("test.txt")?;  // File not imported
}

Solution: Always include necessary imports or use hidden lines:

use std::fs::File;
use std::io;
fn main() -> io::Result<()> {
let file = File::open("test.txt")?;
Ok(())
}

Unrealistic Error Handling

Problem: Examples use .unwrap() everywhere.

fn main() {
    let file = File::open("config.json").unwrap();
    let config: Config = serde_json::from_reader(file).unwrap();
    // ...
}

Solution: Show proper error handling for examples readers will copy:

fn main() -> Result<(), Box<dyn Error>> {
    let file = File::open("config.json")
        .context("Failed to open config file")?;
    let config: Config = serde_json::from_reader(file)
        .context("Failed to parse config")?;
    // ...
    Ok(())
}

Reserve .unwrap() for examples explicitly teaching happy-path concepts.

Context-Dependent Examples

Problem: Example requires context established elsewhere.

#![allow(unused)]
fn main() {
// What is `db`? Where does it come from?
let users = db.query("SELECT * FROM users")?;
}

Solution: Show context or use comments:

#![allow(unused)]
fn main() {
// Assuming `db` is a database connection from setup code
// (see Chapter 3 for database setup)
let users = db.query("SELECT * FROM users")?;
}

Obsolete Examples

Problem: API changes make examples outdated.

Solution: Document the version. Use Cargo.toml in example projects:

[dependencies]
some-crate = "2.1"  # Examples tested with this version

Requesting Code Reviews from Claude Code

After writing examples, request review:

Review all code examples in chapter 5. For each example, check:

1. Does it compile without modification?
2. Are all imports shown or properly hidden?
3. Does error handling match our book's conventions?
4. Would copying this example actually teach the intended concept?
5. Are variable names consistent with earlier chapters?

List any issues found with specific corrections.

Address issues before finalizing the chapter.

Next Steps

With solid code examples in place, the next chapter covers quality control — systematic approaches to ensuring comprehensive, accurate documentation.

Quality Control

Quality in technical documentation means accuracy, comprehensiveness, and usability. This chapter covers systematic approaches to ensuring your book meets these standards through structured review processes and targeted iteration.

The Quality Triad

Technical documentation quality rests on three pillars:

Accuracy — Is the information correct? Do the code examples work? Are the recommendations sound?

Comprehensiveness — Does the content cover what readers need? Are there gaps in the treatment?

Usability — Can readers find what they need? Can they apply what they learn?

Quality control processes must address all three dimensions.

Review Stages

Structure reviews in stages, each with a specific focus:

Stage 1: Technical Accuracy Review

Focus exclusively on correctness:

Review chapter 6 for technical accuracy. Check:

1. All code examples compile and run
2. All commands produce the stated output
3. All API descriptions match current documentation
4. All recommendations are technically sound

Flag any issues with specific corrections. Don't address
style or comprehensiveness yet.

Technical errors undermine reader trust. Fix them first.

Stage 2: Comprehensiveness Review

Assess coverage after accuracy is confirmed:

Review chapter 6 for comprehensiveness. Consider:

1. What questions would a reader have that aren't answered?
2. What edge cases or failure modes aren't discussed?
3. What related topics might readers expect to find here?
4. What would someone implementing this in production need to know?

List gaps by section. Don't write content yet.

Use the gap list to prioritize additions. Not every gap needs filling — some are intentional scope boundaries.

Stage 3: Usability Review

Evaluate findability and applicability:

Review chapter 6 for usability:

1. Can readers scan to find specific information?
2. Are code examples clearly connected to explanations?
3. Is the structure logical for the task readers are trying to accomplish?
4. Would a reader know what to do after finishing each section?

Suggest structural improvements.

Stage 4: Consistency Review

Check alignment with the rest of the book:

Compare chapter 6 against chapters 4 and 5 for consistency:

1. Terminology usage
2. Code style and patterns
3. Section structure and heading levels
4. Depth of explanation for similar concepts
5. Cross-reference format

List inconsistencies with specific corrections.

The Comprehensive Check

After initial drafting, apply a systematic comprehensiveness check. This process surfaces gaps that neither you nor Claude Code initially considered.

The "What Else" Protocol

After completing a chapter draft:

Step 1: Generate the gap list

The chapter on [topic] is drafted. List everything within scope
that should be covered but isn't. Include:
- Topics not mentioned
- Topics mentioned but not explained
- Edge cases not addressed
- Error conditions not covered
- Real-world considerations missing

Just list items. Don't write content.

Step 2: Categorize the gaps

Review the list and categorize:

• Must add — critical for reader success
• Should add — improves comprehensiveness significantly
• Could add — nice to have, if space permits
• Out of scope — belongs elsewhere or is beyond the book's purpose

Step 3: Address gaps systematically

For each "must add" and "should add" item:

Expand the chapter to cover [gap item].
Add this in the most logical location.
Maintain consistency with existing content.

The "Reader Questions" Protocol

Another approach to comprehensiveness:

Read through chapter 6 as a [specific reader persona].
At each section, list questions that reader would have that
aren't answered in the section.

Example personas:

• Junior developer implementing this for the first time
• Senior developer evaluating the technology
• Developer debugging a production issue
• Developer migrating from a different technology

Different personas reveal different gaps.

Iterative Quality Improvement

Quality improves through iteration. Structure iterations with specific goals:

Iteration 1: Foundation

• Basic structure in place
• All sections drafted
• Code examples present but not polished

Iteration 2: Accuracy

• All code examples tested
• All technical claims verified
• All commands checked

Iteration 3: Depth

• Thin sections expanded
• Edge cases added
• Error handling documented

Iteration 4: Completeness

• Comprehensiveness check completed
• Gaps filled
• Cross-references added

Iteration 5: Polish

• Language cleaned up
• Transitions smoothed
• Formatting standardized

Don't mix goals between iterations. Trying to polish prose while adding content produces muddy results.

Quality Checklists

Use checklists to ensure consistent quality across chapters.

Chapter Completion Checklist

## Chapter [N]: [Title] - Quality Checklist

### Accuracy
- [ ] All code examples compile/run
- [ ] All commands produce expected output
- [ ] All API references verified
- [ ] Technical claims fact-checked

### Comprehensiveness
- [ ] "What else" protocol completed
- [ ] "Reader questions" protocol completed
- [ ] Edge cases documented
- [ ] Error conditions covered

### Usability
- [ ] Scannable structure (clear headings)
- [ ] Code examples introduced with context
- [ ] Each section has clear purpose
- [ ] Actionable takeaways present

### Consistency
- [ ] Terminology matches glossary
- [ ] Code style matches conventions
- [ ] Depth matches comparable chapters
- [ ] Cross-references accurate

### Integration
- [ ] Forward references to later chapters
- [ ] Back references to earlier chapters
- [ ] Prerequisites stated
- [ ] Position in learning path clear

Book-Wide Checklist

## Full Book Quality Checklist

### Structure
- [ ] SUMMARY.md matches actual files
- [ ] Chapter order supports learning progression
- [ ] No circular dependencies between chapters
- [ ] Consistent chapter length (within 50% variation)

### Technical
- [ ] All code examples tested
- [ ] Example project builds successfully
- [ ] External links verified
- [ ] Version numbers documented

### Consistency
- [ ] Terminology consistent throughout
- [ ] Code conventions documented and followed
- [ ] Heading hierarchy consistent
- [ ] Voice and tone consistent

### Completeness
- [ ] Introduction sets expectations accurately
- [ ] All promised topics covered
- [ ] Index/glossary complete (if applicable)
- [ ] No dangling cross-references

Automated Quality Checks

Supplement manual review with automated checks:

Link Validation

# Check for broken internal links
mdbook build 2>&1 | grep -i "error\|warning"

Spell Check

# Using aspell with a custom dictionary
find src -name "*.md" -exec aspell check --lang=en \
  --personal=./.aspell-personal {} \;

Create .aspell-personal with technical terms:

personal_ws-1.1 en 0
mdBook
API
async
kubectl
OAuth

Code Block Language Check

# Find code blocks without language specifiers
grep -n "^\`\`\`$" src/*.md

Heading Consistency

# List all headings by level
grep -h "^#" src/*.md | sort | uniq -c | sort -rn

Using Claude Code for Quality Review

Claude Code can perform structured reviews:

Request Format

Perform a [review type] review of [file/chapter].

Focus areas:
- [specific concern 1]
- [specific concern 2]
- [specific concern 3]

Output format:
- List issues by section
- Provide specific corrections
- Rate severity: high/medium/low

Example: Technical Review

Perform a technical accuracy review of chapter-5.md.

Focus areas:
- Do code examples compile and run correctly?
- Are error handling patterns appropriate for production?
- Do the described behaviors match the framework's actual behavior?

For each issue:
1. Quote the problematic text
2. Explain the problem
3. Provide a correction
4. Rate severity

Example: Comprehensiveness Review

Perform a comprehensiveness review of chapter-5.md.

The chapter covers authentication. Consider what a developer
implementing authentication for a new production service would
need to know.

List missing topics in order of importance.
For each topic, briefly explain why it matters.

Handling Review Feedback

When reviews identify issues, process feedback systematically:

Triage: Categorize issues as:

• Fix now (accuracy errors, broken examples)
• Fix soon (comprehensiveness gaps)
• Fix later (minor improvements)
• Won't fix (out of scope, disagree)

Batch similar fixes: Group related issues and address them together:

Address these three consistency issues in chapter 5:
1. [issue 1]
2. [issue 2]
3. [issue 3]

Verify fixes: After making changes, verify the issue is resolved:

Verify that [specific issue] is resolved in the updated chapter.
Check that the fix didn't introduce new problems.

Quality Control Workflow

A complete quality control workflow for a chapter:

1. Draft complete — all content written
2. Self-review — author reads through, notes issues
3. Automated checks — run scripts for links, spelling, formatting
4. Technical review — Claude Code checks accuracy
5. Comprehensiveness review — Claude Code identifies gaps
6. Address issues — fix all high and medium severity items
7. Final read — author confirms all issues addressed
8. Integration check — verify chapter fits with surrounding chapters

Next Steps

With quality content ready, the next chapter covers publishing — building and deploying your mdBook for readers to access.

Publishing

This chapter covers building your mdBook and deploying it for readers. The publishing process transforms your Markdown source files into a polished, navigable website.

Building Locally

Build your book with:

mdbook build

This generates static HTML in the book/ directory (or the path specified in book.toml).

Preview the build:

mdbook serve --open

This starts a local server and opens your browser. Use this during development for live preview with automatic rebuilding on file changes.

Build Output Structure

The generated book/ directory contains:

book/
├── index.html              # Book landing page
├── print.html              # Single-page print version
├── searchindex.json        # Search index
├── searchindex.js          # Search functionality
├── 404.html                # Not found page
├── fonts/                  # Embedded fonts
├── css/                    # Stylesheets
├── FontAwesome/            # Icons
├── clipboard.min.js        # Copy functionality
├── highlight.js            # Syntax highlighting
├── highlight.css           # Highlighting styles
├── book.js                 # Book functionality
├── introduction.html       # Chapter pages
├── getting-started.html
└── ...

All assets are included. The output is fully static and requires no server-side processing.

Deployment Options

GitHub Pages

The most common deployment target. Two approaches:

Approach 1: Deploy from /docs

Configure mdBook to output to docs/:

[build]
build-dir = "docs"

Build and commit:

mdbook build
git add docs/
git commit -m "Build book for GitHub Pages"
git push

In GitHub repository settings:

• Go to Settings > Pages
• Source: "Deploy from a branch"
• Branch: main (or your default branch)
• Folder: /docs

Approach 2: GitHub Actions

Create .github/workflows/deploy.yml:

name: Deploy mdBook

on:
  push:
    branches:
      - main

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install mdBook
        run: |
          mkdir -p $HOME/.local/bin
          curl -sSL https://github.com/rust-lang/mdBook/releases/download/v0.4.36/mdbook-v0.4.36-x86_64-unknown-linux-gnu.tar.gz | tar -xz -C $HOME/.local/bin
          echo "$HOME/.local/bin" >> $GITHUB_PATH

      - name: Build book
        run: mdbook build

      - name: Setup Pages
        uses: actions/configure-pages@v4

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: 'book'

  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

Enable GitHub Pages:

• Go to Settings > Pages
• Source: "GitHub Actions"

This deploys automatically on every push to main.

Netlify

Create netlify.toml in repository root:

[build]
  command = "curl -sSL https://github.com/rust-lang/mdBook/releases/download/v0.4.36/mdbook-v0.4.36-x86_64-unknown-linux-gnu.tar.gz | tar -xz && ./mdbook build"
  publish = "book"

[build.environment]
  RUST_BACKTRACE = "1"

[[redirects]]
  from = "/*"
  to = "/404.html"
  status = 404

Connect your repository to Netlify. Builds trigger automatically on push.

Vercel

Create vercel.json:

{
  "buildCommand": "curl -sSL https://github.com/rust-lang/mdBook/releases/download/v0.4.36/mdbook-v0.4.36-x86_64-unknown-linux-gnu.tar.gz | tar -xz && ./mdbook build",
  "outputDirectory": "book"
}

Import the repository in Vercel's dashboard.

CloudFlare Pages

In CloudFlare Pages settings:

• Build command: curl -sSL https://github.com/rust-lang/mdBook/releases/download/v0.4.36/mdbook-v0.4.36-x86_64-unknown-linux-gnu.tar.gz | tar -xz && ./mdbook build
• Build output directory: book

Self-Hosted

For self-hosted deployment, copy the book/ directory to any static file server:

mdbook build
rsync -avz book/ user@server:/var/www/mybook/

Configure your web server (nginx, Apache, Caddy) to serve static files.

Example nginx configuration:

server {
    listen 80;
    server_name book.example.com;
    root /var/www/mybook;
    index index.html;

    location / {
        try_files $uri $uri/ =404;
    }

    error_page 404 /404.html;
}

Custom Domain Setup

For GitHub Pages with a custom domain:

1. Add CNAME file to your source:

echo "book.yourdomain.com" > CNAME

2. Configure DNS:

   • For apex domain: A record pointing to GitHub's IPs
   • For subdomain: CNAME record pointing to yourusername.github.io

3. Enable HTTPS in repository settings after DNS propagates.

For other platforms, follow their custom domain documentation.

Build Optimization

Reducing Build Size

Minimize the output size for faster loading:

[output.html]
# Disable features you don't need
google-analytics = ""  # Remove analytics
mathjax-support = false  # If not using math

[output.html.playground]
editable = false  # Disable in-browser code editing

Caching for CI

Cache mdBook binary in CI for faster builds:

- name: Cache mdBook
  uses: actions/cache@v4
  with:
    path: ~/.local/bin/mdbook
    key: mdbook-${{ runner.os }}-v0.4.36

- name: Install mdBook
  run: |
    if [ ! -f ~/.local/bin/mdbook ]; then
      mkdir -p ~/.local/bin
      curl -sSL https://github.com/rust-lang/mdBook/releases/download/v0.4.36/mdbook-v0.4.36-x86_64-unknown-linux-gnu.tar.gz | tar -xz -C ~/.local/bin
    fi
    echo "$HOME/.local/bin" >> $GITHUB_PATH

Pre-Publication Checklist

Before deploying a new version:

Content Checks

• All chapters complete
• mdbook build produces no warnings
• Links verified (internal and external)
• Code examples tested
• Spelling and grammar checked

Configuration Checks

• book.toml metadata accurate (title, author, description)
• Repository URL correct (for edit links)
• Theme configured appropriately
• Search enabled

Deployment Checks

• Build succeeds in CI environment
• Custom domain configured (if applicable)
• HTTPS enabled
• 404 page works

Versioning Releases

For books with multiple versions:

Branch-Based Versions

Maintain separate branches for major versions:

main       → latest version
v1.x       → version 1 maintenance
v2.x       → version 2 maintenance

Deploy each branch to a different subdirectory or subdomain.

Version Dropdown

Add a version dropdown using custom JavaScript or a preprocessor. The specific approach depends on your hosting platform and requirements.

Release Tags

Tag releases for reference:

git tag -a v1.0.0 -m "Version 1.0.0 release"
git push origin v1.0.0

Monitoring

After deployment, verify:

1. Accessibility — All pages load correctly
2. Search — Search functionality works
3. Navigation — Sidebar links function
4. Mobile — Responsive layout works on small screens
5. Performance — Pages load in reasonable time

Use browser developer tools to check for console errors or failed resource loads.

Continuous Deployment

With GitHub Actions (or similar CI), every push to main triggers a fresh build and deploy. This enables:

• Frequent small updates
• Confidence that the deployed version matches source
• Rollback by reverting commits

Monitor your CI pipeline for build failures. Fix broken builds immediately — a failing pipeline blocks all updates.

Next Steps

With your book deployed, the next chapter covers best practices — patterns that have proven effective across many documentation projects.

Best Practices

This chapter distills patterns that consistently produce high-quality technical documentation using Claude Code. These practices emerge from extensive use of AI-assisted writing and represent what works well in practice.

Session Management

Start Fresh With Context

Each Claude Code session starts without memory of previous sessions. Begin with context:

I'm continuing work on a technical book about [topic].
Read CLAUDE.md for project conventions.
Read src/SUMMARY.md for current structure.

Today I'm working on chapter 6. Read src/chapter-5.md
to understand the established voice and format.

Investing in context upfront produces better results than correcting drift later.

Single Chapter Focus

Work on one chapter per session. Switching between chapters mid-session introduces inconsistencies and requires re-establishing context.

If a session must span multiple chapters, explicitly reset context:

We're done with chapter 5. Now switching to chapter 6.
Read chapter-6.md to refresh context. The approach
we used in chapter 5 may not apply here.

End With Documentation

At the end of a productive session, document decisions:

Before we end, summarize the key decisions made in this session
that should inform future work. I'll add these to CLAUDE.md.

This preserves institutional knowledge across sessions.

Writing Workflow

Outline Before Prose

Always generate and approve an outline before writing content. Restructuring prose is expensive; restructuring outlines is cheap.

A good outline includes:

• All section headings
• Key points per section
• Placement of code examples
• Estimated proportions (which sections are larger/smaller)

Draft Incrementally

For chapters over 3000 words, draft in sections:

Write sections 1-3 of the outline.

Then:

Continue with sections 4-6, maintaining consistency
with the previous sections.

This keeps each generation focused and prevents quality degradation.

Review Before Refinement

Read each draft before asking for improvements. Your domain expertise identifies issues that systematic prompting might miss.

Specific feedback drives better iteration:

The section on error handling needs more depth on recovery
strategies. Currently it only discusses detection.

vs.

Improve the error handling section.

Preserve Voice

Establish voice early and maintain it:

Read chapters 1-3. Note the voice: direct, practical,
occasionally wry. The reader is a peer, not a student.
Maintain this voice in chapter 4.

Voice inconsistency is jarring for readers. It's easier to maintain than to fix retroactively.

Content Quality

Teach Through Problems

Start sections with the problem being solved:

Write this section by first establishing the problem
(what goes wrong without this technique), then presenting
the solution, then showing it in practice.

Problem-first organization helps readers understand why before how.

Show Don't Tell

Replace abstract statements with concrete examples:

Abstract:

Proper error handling improves user experience.

Concrete:

When a network request fails, displaying "Error: ECONNRESET" tells users nothing. Displaying "Unable to connect to the server. Check your internet connection and try again." tells them what happened and what to do.

Concrete examples stick; abstract claims don't.

Address the Skeptical Reader

For every recommendation, anticipate "why should I?" and "what if I don't?":

This section recommends [practice]. Add:
1. The specific benefits of following this advice
2. The concrete problems that occur when ignoring it
3. When exceptions might apply

Technical readers don't accept assertions without reasoning.

Include Failure Modes

Document what can go wrong:

After explaining how to [do X], add a section on what
can go wrong:
- Common mistakes and how to recognize them
- Error messages readers might encounter
- How to diagnose and fix problems

Complete documentation covers the unhappy path.

Code Example Practices

Prioritize Runnable Over Elegant

An example that readers can copy, paste, and run teaches more than an elegant snippet that requires invisible context.

Include:

• All necessary imports
• Realistic setup code (or hide it appropriately)
• Clear indication of where customization is needed

Show Context With Hiding

Use mdBook's hidden lines to include context without cluttering:

```rust
# use std::collections::HashMap;
# fn main() {
let mut map = HashMap::new();
map.insert("key", "value");
# }
```

The example is complete but readers see only the relevant portion.

Build Examples Progressively

Complex examples should build on simpler ones:

Example 1: Basic operation Example 2: Add error handling Example 3: Add configuration Example 4: Production-ready version

Each step introduces one new concept.

Test Every Example

Untested examples erode trust. Establish a testing strategy:

• Short inline examples: Manual verification during review
• Longer examples: External files with compilation checks
• Complex projects: Full test suites

The confidence "every example works" justifies the investment.

Iteration Practices

Apply Targeted Pushback

Generic pushback produces generic improvements. Specific questions yield specific improvements:

The authentication section explains JWT validation but
doesn't cover:
- Token refresh strategies
- Handling expired tokens gracefully
- What to do when validation fails

Add coverage for these three topics.

Use Multiple Reviewer Perspectives

Apply different review lenses sequentially:

1. Technical accuracy (does it work?)
2. Comprehensiveness (is anything missing?)
3. Usability (can readers apply it?)
4. Consistency (does it match the rest of the book?)

One pass can't catch everything. Multiple focused passes catch more.

Know When to Stop

Iteration has diminishing returns. Stop when:

• Additional pushback yields phrasing changes, not content changes
• The section exceeds necessary scope for the audience
• You're spending time on edge cases readers won't encounter

Good enough that exists beats perfect that doesn't.

Structural Practices

Maintain SUMMARY.md as Source of Truth

All structural changes should flow through SUMMARY.md:

1. Update SUMMARY.md
2. Create/rename/move the actual files
3. Build to verify links

Never have chapter files that aren't in SUMMARY.md.

Use Consistent Heading Hierarchy

Establish a hierarchy and stick to it:

• H1: Chapter title only (one per file)
• H2: Major sections
• H3: Subsections
• H4: Rarely, for detailed breakdowns

Skip levels (H2 → H4) confuse navigation. Going beyond H4 suggests the section should be restructured.

Cross-Reference Strategically

Reference other chapters when:

• The current chapter depends on earlier material
• Related information exists elsewhere
• The current chapter explicitly doesn't cover something

See [Authentication](./authentication.md) for securing these endpoints.

Don't cross-reference for every tangential mention.

Collaboration Practices

Document Conventions

Maintain a living conventions document (CLAUDE.md or similar):

## Terminology
- "endpoint" not "route" not "URL"
- "request handler" not "controller"
- "the user" not "users" (singular reader)

## Code Style
- Rust: use `Result` not `.unwrap()`
- Always show error handling in examples
- Use `example.com` for domain examples

## Formatting
- Code blocks: always specify language
- Lists: sentence case, no terminal punctuation
- Headers: title case

Explicit conventions prevent drift.

Version Control Discipline

Commit frequently with meaningful messages:

Add authentication chapter sections 1-3
Expand error handling with recovery strategies
Fix broken link in chapter 5

Atomic commits enable:

• Easy rollback of problematic changes
• Clear history of what changed and why
• Parallel work on different chapters

Build Before Committing

Verify the book builds before committing:

mdbook build && git add . && git commit -m "message"

Broken builds block others and create unnecessary fix commits.

Mindset Practices

Trust But Verify

Trust Claude Code's output as a starting point, but verify:

• Technical accuracy through testing
• Comprehensiveness through checklists
• Consistency through comparison

This is no different from reviewing any contributor's work.

Maintain Ownership

You are the author. Claude Code is a tool. The book reflects your expertise, judgment, and editorial decisions.

When Claude Code produces something wrong, correct it. When it produces something you disagree with, override it. When it produces something excellent, learn from it.

Invest in the Process

Time spent establishing conventions, documenting decisions, and creating reusable prompts pays dividends across the project. A well-structured writing process produces more content with less effort than ad-hoc sessions.

Summary

These practices form a coherent approach:

1. Manage sessions with explicit context and single-chapter focus
2. Write iteratively from outline to draft to refinement
3. Maintain quality through problem-focused content and working examples
4. Iterate purposefully with targeted feedback and multiple perspectives
5. Structure carefully with consistent hierarchies and cross-references
6. Collaborate effectively through documented conventions and version control

The practices reinforce each other. Following some but not others produces inconsistent results. Following all of them produces excellent technical documentation.

Troubleshooting

This chapter addresses common problems encountered when writing technical books with Claude Code and mdBook, with solutions for each.

Claude Code Issues

Problem: Claude Code Doesn't Remember Previous Sessions

Symptom: Each session starts fresh. Previously established conventions are forgotten.

Solution: Claude Code sessions don't persist context. Always start sessions by referencing your context files:

Read CLAUDE.md and src/SUMMARY.md to understand the project.
Then read src/chapter-5.md for style context.

Maintain a CLAUDE.md file with persistent conventions that should apply to every session.

Problem: Generated Content Is Too Generic

Symptom: Content reads like boilerplate. It lacks specificity and depth.

Solutions:

1. Provide more context:

   This is for developers who already understand [X] and need to
   learn [Y] specifically for [Z use case].
   

2. Specify what you don't want:

   Don't include basic explanations of [fundamental concept] —
   readers already know this.
   

3. Use pushback:

   This is too generic. A senior developer implementing this in
   production would need to know [specific concerns]. Rewrite
   with those details.
   

Problem: Inconsistent Voice or Terminology

Symptom: The chapter uses different terms or a different tone than earlier chapters.

Solutions:

1. Reference existing content:

   Read chapters 2 and 3 first. Match their voice and terminology exactly.
   

2. Specify terminology:

   Use "endpoint" not "route." Use "request handler" not "controller."
   

3. Fix retroactively:

   Review this chapter for terminology consistency with chapter 3.
   List any differences and correct them.
   

Problem: Code Examples Don't Compile

Symptom: Code examples have syntax errors, missing imports, or don't run.

Solutions:

1. Request complete examples:

   All code examples must be complete and compilable. Include all
   necessary imports. Don't assume context.
   

2. Request verification:

   Before finalizing, verify each code example compiles. Fix any
   issues and explain what was wrong.
   

3. Use external files: Store examples in separate files that you can test using the include directive: {{#include ../examples/chapter5/auth.rs}}

Problem: Content Scope Keeps Expanding

Symptom: Each iteration adds more tangential content. The chapter grows unfocused.

Solutions:

1. Define scope explicitly:

   This chapter covers ONLY: [list]
   It explicitly does NOT cover: [list]
   

2. Reject additions:

   That addition is out of scope for this chapter. It belongs in
   chapter 8. Don't include it here.
   

3. Set length targets:

   This section should be 300-400 words. Don't expand beyond that.
   

mdBook Build Issues

Problem: "File not found" Errors

Symptom: mdbook build reports files referenced in SUMMARY.md don't exist.

Solution: Ensure every path in SUMMARY.md has a corresponding file:

# Check for missing files
mdbook build 2>&1 | grep "not found"

Either create the missing files or remove the references from SUMMARY.md.

Problem: Broken Internal Links

Symptom: Links to other chapters produce 404 errors.

Solution: Use relative paths from the current file's location:

<!-- From src/part1/chapter1.md to src/part2/chapter5.md -->
See [Chapter 5](../part2/chapter5.md)

<!-- From src/chapter1.md to src/chapter5.md -->
See [Chapter 5](./chapter5.md)

Verify links by building:

mdbook build 2>&1 | grep -i warning

Problem: Code Blocks Not Highlighting

Symptom: Code appears as plain text without syntax highlighting.

Solutions:

1. Specify the language:

   ```rust
   fn main() {}
   ```
   

   Not:

   ```
   fn main() {}
   ```
   

2. Check language identifier: Use standard identifiers: rust, python, javascript, typescript, go, java, etc.

3. Check for malformed blocks: Ensure exactly three backticks, no spaces before them.

Problem: Build Is Slow

Symptom: mdbook build takes a long time, especially in CI.

Solutions:

1. Cache mdBook binary in CI:

   - uses: actions/cache@v4
     with:
       path: ~/.cargo/bin/mdbook
       key: mdbook-${{ runner.os }}
   

2. Use mdbook serve during development: Incremental rebuilds are faster than full builds.

3. Reduce image sizes: Large images slow builds and page loads. Compress before including.

Problem: Search Not Working

Symptom: Search returns no results or the search box is missing.

Solutions:

1. Ensure search is enabled:

   [output.html.search]
   enable = true
   

2. Rebuild from scratch:

   rm -rf book/
   mdbook build
   

3. Check browser console: JavaScript errors can prevent search from initializing.

Problem: Theme Issues

Symptom: Dark mode doesn't work, wrong colors, theme switcher missing.

Solution: Configure themes in book.toml:

[output.html]
default-theme = "light"
preferred-dark-theme = "ayu"

Available themes: light, rust, coal, navy, ayu

Content Issues

Problem: Chapters Are Uneven Lengths

Symptom: Some chapters are 500 words, others are 5000 words.

Solutions:

1. Set length targets per chapter:

   This chapter should be approximately 3000 words.
   

2. Split long chapters: If a chapter exceeds 5000 words, consider splitting into two chapters.

3. Expand thin chapters:

   This chapter is too brief. What additional topics within
   scope should be covered? What details are missing?
   

Problem: Readers Get Lost

Symptom: Feedback indicates readers can't follow the progression.

Solutions:

1. Add chapter previews: Begin each chapter with what will be covered.

2. Add section summaries: End each major section with key takeaways.

3. Add cross-references:

   As we covered in [Chapter 3](./chapter3.md)...
   

4. Check prerequisites: Each chapter should state what readers need to know first.

Problem: Code Examples Don't Match Text

Symptom: The prose describes one thing but the code shows something different.

Solutions:

1. Review alignment:

   Review this section. Does the text accurately describe what
   the code example shows? Fix any discrepancies.
   

2. Update together: When changing code examples, immediately update the surrounding prose.

3. Use inline comments: Key code lines should have comments matching the textual explanation.

Deployment Issues

Problem: GitHub Pages Not Updating

Symptom: Pushes don't appear on the deployed site.

Solutions:

1. Check Actions tab: Verify the workflow ran successfully.

2. Check Pages settings: Ensure source is configured correctly.

3. Clear browser cache: Old versions may be cached.

4. Verify build output: Check that the built files are in the correct directory.

Problem: Custom Domain Not Working

Symptom: Custom domain returns 404 or wrong site.

Solutions:

1. Verify DNS:

   dig yourdomain.com
   

2. Check CNAME file: Must contain only the domain, no protocol:

   book.yourdomain.com
   

   Not:

   https://book.yourdomain.com
   

3. Wait for propagation: DNS changes can take up to 48 hours.

4. Re-enable HTTPS: After DNS propagates, re-enable HTTPS in repo settings.

Problem: Large Repository Size

Symptom: Repository grows large, clones are slow.

Solutions:

1. Don't commit build output: Add book/ to .gitignore unless using docs-folder deployment.

2. Optimize images: Compress images before committing. Consider storing large assets elsewhere.

3. Clean history: If large files were accidentally committed:

   git filter-branch --tree-filter 'rm -rf book/' HEAD
   

   (Use with caution; rewrites history.)

Process Issues

Problem: Lost Work Between Sessions

Symptom: Decisions and conventions are forgotten between sessions.

Solution: Document everything in persistent files:

• CLAUDE.md: Conventions, terminology, style rules
• STATUS.md: Current progress, open questions
• DECISIONS.md: Key decisions and their rationale

Read these files at the start of each session.

Problem: Inconsistent Quality Across Chapters

Symptom: Some chapters are polished, others are rough.

Solutions:

1. Use a checklist: Apply the same quality checklist to every chapter before considering it complete.

2. Batch similar improvements: Rather than finishing chapters sequentially, do all technical reviews together, all comprehensiveness reviews together, etc.

3. Track status: Maintain a status document showing which chapters have completed which review stages.

Problem: Scope Creep

Symptom: The book grows beyond its original intent, pushing back deadlines.

Solutions:

1. Define scope upfront: Document what the book covers and explicitly what it doesn't.

2. Maintain a "future editions" list: When good ideas emerge that are out of scope, capture them for later rather than adding them now.

3. Review against scope regularly: Before each chapter, verify it's within the original scope.

Getting Help

If you encounter issues not covered here:

1. mdBook documentation: rust-lang.github.io/mdBook
2. mdBook issues: github.com/rust-lang/mdBook/issues
3. Claude Code help: github.com/anthropics/claude-code/issues