asepharyana-hub-guide/skills/documentation/SKILL.md

name, description

name	description
documentation	Best practices for software documentation — README, API docs, ADRs, inline comments, changelogs, and knowledge base organization. Use when writing README files, designing documentation strategy, adding inline comments, or whenever the user mentions "documentation," "README," "ADR," "changelog," "docstring," "wiki," "documentation as code," or "docs."

Documentation Best Practices

The Minimalist Philosophy

"Produce no document unless its need is immediate and significant." — Robert C. Martin

Documentation has ongoing cost: maintenance, outdated content, reader trust erosion. Write less, maintain ruthlessly.

Rule: If a document would be wrong within 6 months, don't write it — automate it or make the code self-explanatory.

Documentation Types (by audience)

1. README — for newcomers

Every project needs one. Answers 4 questions in order:

1. What is this? — one-paragraph description
2. Why does it exist? — what problem it solves
3. How do I run it? — quickstart: install → configure → run
4. Where do I go for help? — link to issues, docs, chat

# project-name
Brief description (1-2 sentences).

## Quickstart
```bash
npm install
cp .env.example .env
npm run dev

Configuration

Key environment variables, config files.

API

Link to OpenAPI spec or API docs.

Development

Testing, linting, building, contributing guide.

**README anti-patterns:**
- ❌ Outdated setup steps (worse than no setup guide)
- ❌ Long architecture essays (put in ADR or docs/)
- ❌ Contributor lists (git log handles this)
- ❌ Badges from tools you don't use

### 2. ADRs (Architecture Decision Records) — for maintainers

Record *why* a decision was made, not *what* was decided (that's in the code).

docs/adr/ ├── 001-use-postgres-for-primary-store.md ├── 002-use-dapr-for-pub-sub.md └── 003-migrate-to-biome-from-eslint.md

**Template:**
```markdown
# ADR-001: Use PostgreSQL for Primary Store

**Date:** 2024-01-15
**Status:** Accepted | Proposed | Deprecated | Superseded

## Context
Why this decision was needed, what alternatives were considered.

## Decision
What was decided and why over alternatives.

## Consequences
What becomes easier, harder, or needs migration.

3. API Documentation — for consumers

• REST: OpenAPI 3.x spec. Generate from code (Hono Zod OpenAPI, FastAPI Swagger).
• GraphQL: Schema is documentation — auto-generated from SDL.
• Libraries: API reference (JSDoc, rustdoc, godoc, pydoc).
• Include: endpoint/method, params, request/response schema, errors, example, auth.

4. Inline Comments — for future developers

Good comments (rare but valuable):

// WHY: This ordering ensures we process the oldest items first
// so failed retries don't starve newer entries. Priorities > 5
// are reserved for system-internal events.

Bad comments (delete on sight):

// ❌ Redundant
i++ // increment i

// ❌ Misleading (out of date)
// This function validates input (it no longer does)

// ❌ Mumbling
// handle the thing

// ❌ Journal
// 2024-01-15: fixed the bug

// ❌ Commented-out code
// const old = calcTotal(items);

5. CHANGELOG.md — for users

Auto-generated from commits (release-please, changie, git-cliff). Never manual.

# Changelog

## [1.2.0] - 2025-06-15
### Added
- feat(auth): Google OAuth sign-in
- feat(ui): dark mode toggle

### Fixed
- fix(billing): handle null currency in invoice generation
- fix(api): rate-limit headers on error responses

### Changed
- chore(deps): update TypeScript to 5.5

6. How-to Guides — for specific tasks

• Focused, task-oriented. One guide = one task.
• "How to add a new service" not "architecture overview."
• Keep in docs/ directory alongside the code.

Architecture (for docs/)

docs/
├── add-new-app.md        # How-to guide
├── deployment.md         # Deployment guide
├── adr/                  # Architecture Decision Records
├── diagrams/             # Architecture diagrams (keep simple)
└── runbooks/             # Incident response procedures

Automation

• Pre-commit check — warn if README has no quickstart.
• CI check — verify ADR links are valid.
• OpenAPI validation — CI validates spec file is up to date.
• Dependabot/Renovate — keeps dependency docs fresh automatically.

Documentation Anti-patterns

• ❌ Rotting docs — outdated docs are worse than no docs. Delete or update.
• ❌ Copy-paste docs — duplicated content across files. Cross-reference instead.
• ❌ Epic README — README that tries to document everything. Split into docs/.
• ❌ Documenting the obvious — // This function saves a user
• ❌ No code examples — abstract docs without concrete usage are useless.
• ❌ No tone — documentation can be clear without being dry. A little personality helps.