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.