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