developersglobal/ai-agent-skills/documentation

Overview

Code explains what. Documentation explains why. The most valuable documentation records decisions that aren't obvious from reading the code: why this architecture, why this tradeoff, why not the obvious alternative.

When to Use

• After any significant architectural decision
• Before complex code that future maintainers will question
• When an operational procedure isn't self-evident
• When a non-obvious tradeoff was made

Process

Step 1: Architectural Decision Records (ADRs)

For every significant architectural decision:

1. Write an ADR with:

• Context: What was the situation requiring a decision?
• Decision: What was decided?
• Alternatives considered: What else was evaluated and why rejected?
• Consequences: What are the positive and negative consequences?
• Status: Proposed | Accepted | Deprecated | Superseded

1. Store ADRs in docs/decisions/ as numbered markdown files.

Verify: Every significant decision in the last sprint has an ADR.

Step 2: Code-Level Documentation

1. Document the WHY, not the WHAT:

• ✅ // Using exponential backoff here — the payment API has strict rate limits (3 req/sec)
• ❌ // Retry the request

1. Document non-obvious algorithmic choices.
2. Document external constraints (rate limits, API quirks, platform limitations).
3. Remove comments that state the obvious — they add noise.

Verify: Every non-obvious code block has a "why" comment.

Step 3: Runbooks

1. For every production process that humans execute, write a runbook:

• When is this runbook used?
• What steps to execute?
• What does "done" look like?
• What could go wrong and how to recover?

1. Runbooks live in docs/runbooks/.

Verify: Every on-call alert has a linked runbook.

Step 4: README Currency

1. README reflects current state (not v1 state).
2. Setup instructions work on a fresh machine.
3. Architecture diagram updated after significant changes.

Common Rationalizations (and Rebuttals)

Verification

• [ ] ADRs written for significant architectural decisions
• [ ] Non-obvious code blocks have "why" comments
• [ ] Every production alert has a linked runbook
• [ ] README is current and setup instructions work

References

• git-workflow skill
• Michael Nygard's ADR template