174 lines
4.9 KiB
Markdown
174 lines
4.9 KiB
Markdown
---
|
|
name: writing-documentation
|
|
description: Write clear, effective technical documentation following industry-proven patterns from exemplary projects and authoritative style guides, with built-in countermeasures for common LLM documentation issues
|
|
---
|
|
|
|
# Writing Documentation Skill
|
|
|
|
## Documentation Types (Diátaxis Framework)
|
|
|
|
- **Tutorial** - Learning-oriented, step-by-step
|
|
- **How-to** - Task-oriented, specific problems
|
|
- **Reference** - Technical specifications
|
|
- **Explanation** - Clarifies concepts
|
|
|
|
Details in `references/best-practices.md`.
|
|
|
|
## Writing for Claude Code
|
|
|
|
**CRITICAL**: When writing documentation that Claude reads (SKILL.md, CLAUDE.md, commands, agents):
|
|
|
|
### 1. Test Claude's Base Knowledge First
|
|
|
|
Verify what Claude already knows:
|
|
|
|
```bash
|
|
# Use haiku for cost-effective testing (gives same quality answers as sonnet)
|
|
claude --print --model haiku "Do NOT use any skills. How would you [perform task]?"
|
|
claude --print --model haiku "Do NOT use any skills. When should you [make decision]?"
|
|
```
|
|
|
|
### 2. Document ONLY Unique Patterns
|
|
|
|
Include only what Claude wouldn't naturally do:
|
|
|
|
- ✓ Opinionated architectural choices
|
|
- ✓ Counter-intuitive decisions
|
|
- ✓ Project-specific conventions
|
|
- ✓ Non-default patterns
|
|
|
|
Remove redundant content:
|
|
- ✗ Standard library usage
|
|
- ✗ Common best practices
|
|
- ✗ Well-known patterns
|
|
- ✗ Basic language features
|
|
|
|
### 3. Example: React Skill Reduction
|
|
|
|
Testing revealed Claude knows TanStack Query/Zustand/RTL patterns but doesn't default to:
|
|
- "Test stores, not components" (counter-cultural)
|
|
- "NO useState for complex logic" (prescriptive)
|
|
- "Inline actions unless repeated 2+" (specific rule)
|
|
|
|
Result: 328→125 lines (-62%) by documenting only unique opinions.
|
|
|
|
## Verifying Technical Accuracy
|
|
|
|
### API Verification Workflow
|
|
|
|
When documenting unfamiliar APIs or libraries:
|
|
|
|
**1. Launch researcher agent:**
|
|
|
|
```
|
|
Use Task tool to launch researcher agent to verify [API/library] documentation
|
|
```
|
|
|
|
Researcher agent uses Context7 MCP to fetch official API docs and verify method signatures.
|
|
|
|
**2. Read the codebase:**
|
|
|
|
For internal/project APIs:
|
|
|
|
```
|
|
Read relevant source files to verify method signatures exist
|
|
```
|
|
|
|
**3. State version requirements:**
|
|
- Specify versions when certain: `# Using pandas 2.0+ DataFrame.merge()`
|
|
- Add verification note when uncertain: `# Verify this API exists in your version`
|
|
|
|
**4. Direct to official docs:**
|
|
Add link to authoritative source.
|
|
|
|
### Security Verification
|
|
|
|
**Required checks before documenting code:**
|
|
|
|
1. **SQL**: Parameterized queries, never string concatenation
|
|
2. **YAML**: `yaml.safe_load()`, never `yaml.load()`
|
|
3. **Credentials**: Environment variables, never hard-coded
|
|
4. **Input**: Always validate before processing
|
|
5. **Errors**: Handle network/file operations
|
|
|
|
Use researcher agent if uncertain about security best practices.
|
|
|
|
## Code Example Requirements
|
|
|
|
### Every Example Must Include
|
|
|
|
1. **All imports and dependencies**
|
|
2. **Complete, copy-paste ready code** (no ellipsis or pseudo-code)
|
|
3. **Expected output** when relevant
|
|
4. **Error handling** for production use
|
|
5. **Context explaining "why"**
|
|
|
|
Example:
|
|
|
|
```python
|
|
# Process in batches of 1000 to avoid memory exhaustion.
|
|
# Testing: smaller (100) = 3x overhead, larger (10000) = OOM on 8GB systems.
|
|
BATCH_SIZE = 1000
|
|
|
|
for batch in chunks(items, BATCH_SIZE):
|
|
process_batch(batch)
|
|
```
|
|
|
|
### Production-Ready Requirements
|
|
|
|
Include when relevant:
|
|
- Authentication/authorization
|
|
- Logging for debugging
|
|
- Rate limiting and retries
|
|
- Timeout handling
|
|
- Resource cleanup
|
|
|
|
See `references/best-practices.md` for complete production-ready examples.
|
|
|
|
## Using docs-reviewer Agent
|
|
|
|
After writing documentation:
|
|
|
|
```
|
|
Use docs-reviewer agent to ruthlessly simplify
|
|
```
|
|
|
|
The agent challenges every element's necessity, asking "Would the documentation still be clear without this?"
|
|
|
|
**Critical for**:
|
|
- CLAUDE.md, SKILL.md files
|
|
- Slash commands and agents
|
|
- Any Claude Code documentation
|
|
|
|
Eliminates:
|
|
- Motivational language
|
|
- Redundant examples
|
|
- Unnecessary context that doesn't change behavior
|
|
|
|
## LLM Self-Checklist
|
|
|
|
Before publishing:
|
|
|
|
**Verification:**
|
|
- [ ] Verified APIs exist (researcher agent, codebase read, or official docs)
|
|
- [ ] Code is complete and secure (all imports, parameterized queries, error handling)
|
|
- [ ] Examples are production-ready (auth, logging, retries, timeouts)
|
|
|
|
**Content Quality:**
|
|
- [ ] Context and "why" explained, not just "what"
|
|
- [ ] Specific details, not generic (40ms not "significant", name technologies not "various aspects")
|
|
- [ ] Consistent terminology throughout
|
|
- [ ] Appropriate hedging (direct for facts, hedge only when uncertain)
|
|
|
|
**Claude Code Docs:**
|
|
- [ ] Tested base knowledge with `claude --print`
|
|
- [ ] Documented only unique patterns
|
|
- [ ] Applied docs-reviewer agent for ruthless simplification
|
|
|
|
## References
|
|
|
|
Research foundation in `references/`:
|
|
- `exemplary-projects.md` - Analysis of well-documented projects
|
|
- `best-practices.md` - Authoritative style guide synthesis
|
|
- `llm-pitfalls.md` - LLM-specific quality issues
|