# Documentation And Adrs

> Write documentation that stays accurate and decisions that stay recorded

- Skill: `vignesh2027/documentation-and-adrs` (Agent Skill)
- Install (CLI): `npx skillmds@latest add vignesh2027/documentation-and-adrs`
- Raw SKILL.md: https://api.skillmd.com/api/skills/vignesh2027/documentation-and-adrs/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: vignesh2027 (https://skillmd.com/u/vignesh2027)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/vignesh2027/documentation-and-adrs

---


## Overview

Documentation that is wrong is worse than no documentation — it confidently misleads. This skill writes documentation that is minimal, accurate, and maintained. It also captures architectural decisions (ADRs) so future engineers understand why the system is the way it is.

## When to Use

- Before shipping a new feature or API
- When changing a public interface
- When making an architectural decision that is hard to reverse
- When documenting a non-obvious system behavior

## Process

### Step 1: Audience-first
Before writing: who is the reader? What do they already know? What do they need to do after reading this? Write for that person, not for yourself.

### Step 2: Document the why, not just the what
The code describes what. The documentation must describe: why this design, what was rejected, what trade-offs were made. This is what prevents future engineers from "improving" something that can't be improved.

### Step 3: README structure
Good README:
1. What is this? (one sentence)
2. Why does it exist? (one paragraph)
3. Quick start (the first 5 minutes)
4. Core concepts (only what's non-obvious)
5. Reference (exhaustive, machine-readable if possible)
6. Contributing (link to CONTRIBUTING.md)

### Step 4: API documentation
For every public API endpoint or function:
- Purpose (one sentence)
- Parameters: name, type, constraints, required/optional
- Return value: type, shape, possible values
- Error cases: what errors can occur and when
- Example: one complete working example

### Step 5: Architecture Decision Records (ADRs)
Write an ADR for every decision that is:
- Hard to reverse
- Non-obvious in its rationale
- Likely to be questioned by a future engineer

ADR format:
```markdown
# ADR-NNN: [Short Title]

## Status
[Proposed | Accepted | Deprecated | Superseded by ADR-NNN]

## Context
[What situation led to this decision?]

## Decision
[What was decided?]

## Alternatives Considered
[What else was evaluated and why was it rejected?]

## Consequences
[What becomes easier or harder as a result?]
```

### Step 6: Keep documentation close to the code
Documentation in a separate wiki will drift. Prefer: inline docstrings for functions, README.md in each directory, ADRs in a `docs/decisions/` folder.

### Step 7: Test your documentation
Have someone unfamiliar with the system follow the quick start. If they get stuck, the documentation is wrong.

## Anti-Rationalizations

**"The code is self-documenting"**
Code says what. Documentation says why. No code is self-documenting for the why.

**"No one reads ADRs"**
No one reads ADRs until they need to. That moment always comes.

## Verification Requirements

- [ ] README has: what, why, quick start, contributing
- [ ] All public APIs documented with parameters, returns, and examples
- [ ] ADR written for hard-to-reverse decisions
- [ ] Documentation reviewed by someone unfamiliar with the system
- [ ] Docs live close to the code they describe