Documentation Skills
Best practices for creating effective documentation during Claude Code sessions.
Session Documentation
Incremental Summary Documents
When working through multiple related issues in a session:
- Create summary after each major fix:
- FIX_SUMMARY.md - First issue resolved - FISH_CLASSIFICATION_FIX_SUMMARY.md - Second issue - TAXONOMY_COMPLETE_SUMMARY.md - Final state
- Benefits:
- User can reference specific fixes - Clear audit trail of changes - Easy to see what was done and why - Supports future troubleshooting
- Include in each summary:
- Problem statement: What was the issue? - Root cause: Why did it happen? - Species/items affected: With counts for verification - Solution applied: Step-by-step what was done - Files modified: Complete list with paths - Verification results: Show the fix worked - Next steps: What to do with the results
Example Structure
# [Issue Name] - [STATUS]
## Problem
[Clear description of what was wrong]
## Root Cause
[Why the problem occurred]
## Items Fixed (N total)
| Item | Details | Category |
|------|---------|----------|
| ... | ... | ... |
## Solution Applied
1. [Step 1]
2. [Step 2]
...
## Verification Results
✓ [What was verified]
✓ [Counts match]
## Files Modified
1. `file1.txt` - [what changed]
2. `file2.txt` - [what changed]
## Next Steps
[What the user should do now]When to Create Summaries
- After fixing a significant bug: Document root cause and solution
- After completing a major task: Show what was accomplished
- After each iteration in multi-step fixes: Track progress
- At session end: Comprehensive final state summary
Documentation File Naming
Use descriptive names that indicate:
- What was fixed:
FISH_CLASSIFICATION_FIX_SUMMARY.md - Scope:
TAXONOMY_COMPLETE_SUMMARY.md - Status: Include "FIXED", "COMPLETE", "FINAL" in filename
Avoid generic names like SUMMARY.md or NOTES.md.
Related Skills
- Skill Management: Capturing learnings from documentation
- Token Efficiency: Concise yet complete documentation