Documentation

Documentation

Purpose: Write clear, maintainable documentation for code and APIs. Goal: Self-documenting code, useful comments, comprehensive READMEs. Note: For implementation, see C# Development or Python Development.

When to Use This Skill

• Writing or updating README files
• Documenting APIs with OpenAPI/Swagger
• Creating architecture decision records (ADRs)
• Adding inline code documentation
• Setting up documentation tooling

Prerequisites

• Markdown formatting knowledge

Decision Tree

Documenting something?
+- New project/repo? -> README.md (setup, usage, contributing)
+- Public API?
| +- REST API -> OpenAPI/Swagger spec
| - Library -> XML docs / docstrings on all public members
+- Architecture decision? -> ADR (docs/artifacts/adr/ADR-NNN.md)
+- Complex logic?
| +- WHY it works this way -> Code comment
| - HOW to use it -> Doc comment / docstring
+- Code self-explanatory?
| - Yes -> No comment needed (good naming > comments)
- Inline comment?
 +- Explains WHY (business rule, workaround) -> Keep it
 - Explains WHAT (obvious from code) -> Remove it

Documentation Hierarchy

Documentation Pyramid:

 /\
 /API\ External API docs (OpenAPI/Swagger)
 /------\
 / README \ Project documentation
 /----------\
 / Inline Docs\ Function/class documentation
 /--------------\
 / Code Quality \ Self-documenting code (naming, structure)
/------------------\

Best Code = Minimal comments needed

Self-Documenting Code

Code Should Explain WHAT

[FAIL] Bad: Needs comment to understand
 # Check if user can access
 if u.r == 1 or u.r == 2:
 return True

[PASS] Good: Self-explanatory
 if user.role == Role.ADMIN or user.role == Role.MODERATOR:
 return True

[PASS] Better: Extract to function
 if user.hasModeratorPermissions():
 return True

Names Should Be Descriptive

Variables:
 [FAIL] d, tmp, data, x
 [PASS] daysSinceLastLogin, userCount, orderTotal

Functions:
 [FAIL] process(), handle(), do()
 [PASS] calculateShippingCost(), validateEmailFormat(), sendWelcomeEmail()

Classes:
 [FAIL] Manager, Handler, Processor, Helper
 [PASS] OrderRepository, EmailValidator, PaymentGateway

Core Rules

Anti-Patterns

• Stale Docs: Documentation that contradicts current code behavior -> Tie doc updates to code changes in the same PR; add doc review to checklist
• Comment Parrot: Comments that restate the code (i += 1 // increment i) -> Only comment WHY, never WHAT; delete comments that repeat the code
• README Novel: Putting all documentation in a single massive README -> Split into focused docs/ files (CONTRIBUTING.md, ARCHITECTURE.md) and link from README
• Tribal Knowledge: Critical setup or deployment steps live only in someone's head -> Write runbooks and onboarding guides; if you explained it twice, document it
• API Doc Drift: Hand-written API docs that diverge from actual endpoints -> Generate API docs from code annotations (OpenAPI/Swagger) and validate in CI
• TODO Graveyard: Scattering TODO comments that never get addressed -> Create issues for TODOs with deadlines; remove or resolve stale TODOs regularly
• Screenshot Docs: Using images where text would be searchable and maintainable -> Use code blocks, ASCII diagrams, or Mermaid for diagrams; reserve images for UX mockups

See Also: API Design - C# Development - Python Development

Scripts

Troubleshooting

References

• Inline Docs Comments
• Readme Templates
• Api Architecture Docs

Source: jnPiyush/AgentX — distributed by TomeVault.