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:
- Draft complete — all content written
- Self-review — author reads through, notes issues
- Automated checks — run scripts for links, spelling, formatting
- Technical review — Claude Code checks accuracy
- Comprehensiveness review — Claude Code identifies gaps
- Address issues — fix all high and medium severity items
- Final read — author confirms all issues addressed
- 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.