Skill207 repo starsupdated today

documentation

This skill establishes a documentation practice emphasizing decision rationale over implementation details. Use it to create Architectural Decision Records for significant choices, add inline comments explaining non-obvious code logic and constraints, write operational runbooks for production procedures, and maintain current README files. Apply this skill whenever architectural decisions are made, before complex code sections, during operational procedure definition, or when non-obvious tradeoffs occur to ensure future maintainers understand not just what the system does but why those specific approaches were chosen.

View source Repository: ai-agent-skills

Install in Claude Code

Copy

git clone --depth 1 https://github.com/DevelopersGlobal/ai-agent-skills /tmp/documentation && cp -r /tmp/documentation/skills/documentation ~/.claude/skills/documentation

Then start a new Claude Code session; the skill loads automatically.

Definition

SKILL.md

## 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
2. 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

3. Document the WHY, not the WHAT:
   - ✅ `// Using exponential backoff here — the payment API has strict rate limits (3 req/sec)`
   - ❌ `// Retry the request`
4. Document non-obvious algorithmic choices.
5. Document external constraints (rate limits, API quirks, platform limitations).
6. Remove comments that state the obvious — they add noise.

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

### Step 3: Runbooks

7. 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?
8. Runbooks live in `docs/runbooks/`.

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

### Step 4: README Currency

9. README reflects current state (not v1 state).
10. Setup instructions work on a fresh machine.
11. Architecture diagram updated after significant changes.

## Common Rationalizations (and Rebuttals)

| Excuse | Rebuttal |
|--------|----------|
| "The code is self-documenting" | Code says what; documentation says why. Both are needed. |
| "I'll document it later" | The context in your head right now is irreplaceable. Write it now. |
| "Docs go stale" | Outdated docs are better than no docs. Update when you touch the code. |

## 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](../git-workflow/SKILL.md)
- [Michael Nygard's ADR template](https://github.com/joelparkerhenderson/architecture-decision-record)