API Documentation Writer Skill

Purpose

Create comprehensive, accurate API reference documentation by reading source code and extracting exact method signatures. Follows the Diátaxis Reference pattern for information-oriented documentation with zero tolerance for fabricated methods or incorrect signatures.

Diátaxis Framework: Reference Documentation

Reference Type Characteristics:

• Information-oriented - Describes the machinery, not how to use it
• Technical descriptions - Facts about APIs, parameters, return types
• Complete coverage - Every public method and type documented
• Structured consistently - Same format for all entries
• Exact signatures - Verified against source code
• Minimal examples - Usage demonstrations, not step-by-step tutorials

What NOT to Include:

• ❌ Tutorials (learning-oriented) - Use tutorial-writer skill
• ❌ How-To guides (problem-oriented) - Use migration-guide-writer skill
• ❌ Explanations (understanding-oriented) - Link to separate explanation docs
• ❌ Marketing language - Technical descriptions only

Critical Rules (Zero Tolerance)

P0 - CRITICAL Violations (Must Fix)

1. Fabricated Methods - Methods that don't exist in source code
2. Wrong Signatures - Parameter types, names, or order don't match source
3. Invalid Examples - Code that won't compile or uses fake imports
4. Unverified Performance Claims - Numbers without benchmark evidence

P1 - HIGH Violations (Should Fix)

5. Missing Source References - Not citing which file/method documented
6. Incomplete Coverage - Missing public methods
7. Marketing Language - Buzzwords instead of technical descriptions

P2 - MEDIUM Violations

8. Structural Issues - Not following template consistently
9. Redundancy - Repeating information unnecessarily

Workflow (Quick Summary)

Core Steps

1. Discovery: Identify language, locate public API surface using grep/glob patterns, create checklist
2. Extraction: Read source files, copy EXACT signatures (no paraphrasing), extract comments and error conditions
3. Documentation: Use standardized templates (types, functions, constants), follow Diátaxis Reference pattern
4. Examples: Write complete, runnable examples with imports and proper error handling
5. Verification: Verify signatures match source exactly, check completeness, eliminate marketing language
6. Organization: Structure logically (Overview → Types → Functions → Constants → Examples)

For detailed step-by-step workflow with bash commands, templates, and verification checklists:

Read `~/.claude/skills/api-doc-writer/references/WORKFLOW-STEPS.md`

For API documentation templates (types, functions, constants):

Read `~/.claude/skills/api-doc-writer/references/TEMPLATE-EXAMPLES.md`

Use when: Performing API documentation, need specific templates, or understanding each step

---

Common Pitfalls (Quick Summary)

Critical Issues to Avoid

1. Paraphrasing Signatures: Copy exact signature from source (include receiver types, pointer symbols)
2. Fabricating Methods: ONLY document methods that exist in source code (verify first)
3. Wrong Parameter Types: Match types exactly (string vs TaskId, pointer vs value)
4. Missing Error Conditions: Document specific error conditions from code logic
5. Non-Runnable Examples: Include all imports, use correct syntax and real APIs
6. Line Number References: Use method names, not line numbers (they change)
7. Marketing Language: Use technical descriptions ("provides CRUD operations" not "blazing-fast")

For detailed pitfall examples with bad/good comparisons:

Read `~/.claude/skills/api-doc-writer/references/PITFALLS.md`

Use when: Need concrete examples of common mistakes to avoid

---

Integration with Other Skills

Works With:

• api-documentation-verify - Verify reference docs for accuracy
• migration-guide-writer - Reference docs show new API signatures
• tutorial-writer - Tutorials link to reference for detailed API info

Invokes:

• None (standalone skill, but uses Read tool extensively)

Invoked By:

• User (manual invocation)
• As part of documentation workflow

Output Format

Primary Output: Markdown file with structured API reference

File Location:

• docs/api/[package-name].md for package documentation
• API.md in project root for main API
• docs/reference/[module-name].md for module documentation

Include at end of document:

---

## Documentation Metadata

**Last Updated**: [Date]
**Source Code Version**: [Commit SHA or version]
**Verification Status**: ✅ All APIs verified against source code
**Source Files**:

- `path/to/file1.go`
- `path/to/file2.go`

## Verification Checklist Completed:

- ✅ All methods verified against source
- ✅ All signatures exactly match
- ✅ All examples use real imports
- ✅ No fabricated methods
- ✅ No marketing language
- ✅ Source references included

Time Estimates

Small API (< 10 public methods): 30-45 minutes Medium API (10-30 public methods): 1-2 hours Large API (30+ public methods): 2-4 hours Complex API with types (many types and methods): 4-8 hours

Example Usage

# Manual invocation
/skill api-doc-writer

# With specific package
/skill api-doc-writer pkg/services/task

# User request
User: "Document the TaskService API"
Assistant: "I'll use the api-doc-writer skill to create comprehensive API documentation"

Success Criteria

Documentation is complete when:

• ✅ All public APIs discovered and documented
• ✅ All signatures verified against source code
• ✅ All examples use real imports and verified APIs
• ✅ No fabricated methods or wrong signatures
• ✅ Source references included for all entries
• ✅ Error conditions documented from code
• ✅ Verification checklist completed
• ✅ No marketing language or buzzwords
• ✅ Structured consistently using template

References

• Diátaxis Framework: https://diataxis.fr/reference/
• Technical Documentation Expert Agent
• REFERENCE.md template in this skill directory

---

Related Agent

For comprehensive documentation guidance that coordinates this and other documentation skills, use the documentation-coordinator agent.