---
id: productivity-documentation
title: Documentation — README / ADR / Runbook
category: Coding
status: draft
source_trust_level: B
verification_status: conceptual
created_at: 2026-05-09
updated_at: 2026-05-09
tags: [productivity, docs, vibe-coding]
tech_stack: { language: "Markdown", applicable_to: ["Engineering"] }
applied_in: []
aliases: [README, ADR, architecture decision record, runbook, docs as code, Diataxis]
---

# Documentation

> 코드 자체로 충분 X. **README, ADR (architectural decisions), runbook, API docs, onboarding**. Doc as code (markdown in git). Diataxis framework.

## 📖 핵심 개념
- README: 프로젝트의 입구.
- ADR: 결정의 기록 (왜 X 가 아닌 Y 선택).
- Runbook: incident / migration 의 step.
- Diataxis: 4 categories — tutorial / how-to / reference / explanation.

## 💻 코드 패턴

### README template
```markdown
# Project Name

Short description (1-2 sentences).

## Status
🚧 Active development | ⚠️ Maintenance only | ⛔ Deprecated

## Quickstart
```bash
git clone ...
cd project
yarn install
yarn dev
```

## Setup
- Node 20+
- Postgres 16+
- Redis 7+
- Env vars in `.env.example`

## Development
```bash
yarn dev          # local dev server
yarn test         # tests
yarn build        # production build
yarn lint         # lint
yarn typecheck    # tsc
```

## Deploy
See [DEPLOY.md](./DEPLOY.md)

## Architecture
[Brief overview, link to ADRs]

## Contributing
See [CONTRIBUTING.md](./CONTRIBUTING.md)

## License
MIT
```

### ADR (Architecture Decision Record)
```markdown
# 0001. Use Postgres for primary database

Date: 2026-05-09
Status: Accepted
Authors: @alice, @bob

## Context
We need a primary database for user / order / inventory data.

Requirements:
- ACID transactions
- Strong relational queries
- Mature ecosystem
- Cloud-managed option

## Options considered
1. **Postgres** — mature, strong SQL, JSON support
2. **MySQL** — popular, simpler
3. **MongoDB** — flexible schema
4. **DynamoDB** — managed, scales

## Decision
**Postgres** because:
- Best-in-class SQL features (CTE, window, JSONB)
- Free + open
- Great cloud options (RDS, Aurora, Supabase, Neon)
- Team familiar

## Consequences
- ✅ Strong analytics queries
- ✅ JSONB for flexible data
- ⚠️ Need to manage scaling (PgBouncer for connections)
- ⚠️ Manual sharding 필요 시 — Citus / 자체

## References
- https://www.postgresql.org/
```

→ Numbered + immutable. 새 결정 = 새 ADR + supersede 옛.

### ADR storage
```
docs/
├── adr/
│   ├── 0001-use-postgres.md
│   ├── 0002-use-react-typescript.md
│   ├── 0003-monorepo-with-turborepo.md
│   └── README.md           # 목록
```

### adr-tools (자동화)
```bash
adr-new "Use Redis for cache"
# → 0004-use-redis-for-cache.md (template)

adr-link 4 supersedes 1
# → 0001 가 superseded by 0004
```

### Diataxis framework
```
4 종류 documentation:

1. Tutorial (학습): "Get started with X"
   - Step-by-step, guided
   - 새 사용자
   - 작은 win
   
2. How-to (작업): "How to do X"
   - Recipe / cookbook
   - 알 사용자
   - 빠른 reference
   
3. Reference (정보): API spec, config options
   - 정확 / 완전
   - 알파벳 정렬
   
4. Explanation (이해): "Why does X work this way"
   - Concept, history
   - 깊이 학습

→ 한 문서 가 한 종류. 섞으면 헷갈림.
```

### docs/ 구조
```
docs/
├── README.md              # 입구
├── tutorials/
│   └── getting-started.md
├── how-to/
│   ├── deploy.md
│   ├── add-feature-flag.md
│   └── debug-slow-query.md
├── reference/
│   ├── api.md
│   └── config.md
├── explanation/
│   ├── architecture.md
│   └── why-postgres.md
├── adr/
└── runbooks/
    ├── api-down.md
    └── db-failover.md
```

### API docs (자동)
```ts
// OpenAPI spec → 자동 docs
// Scalar / Stoplight / Redoc / Swagger UI

// 또는 TypeDoc
yarn typedoc src/index.ts
```

### Code comment 가이드
```ts
// ❌ "i 를 increment"
i++;  // 의미 없음

// ❌ "Set name to user.name"
this.name = user.name;

// ✅ "왜" 가 명확하지 않을 때
// User.deletedAt 가 null 이라도 admin 가 soft-delete 했을 수 있음
const isActive = user.deletedAt === null && user.adminBan === null;

// ✅ Tricky math / algorithm
// Boyer-Moore voting algorithm — O(N) majority element
```

### JSDoc / TSDoc
```ts
/**
 * Calculates the order total including tax and shipping.
 *
 * @param items - Order line items
 * @param region - Shipping region for tax calculation
 * @returns Total in USD with 2 decimal precision
 * @throws {InvalidRegionError} When region not supported
 *
 * @example
 * ```ts
 * const total = calculateTotal(items, 'US-CA');
 * // 99.99
 * ```
 */
function calculateTotal(items: Item[], region: Region): number {
  // ...
}
```

### Changelog (KEEPACHANGELOG)
```markdown
# Changelog

All notable changes to this project will be documented in this file.

## [Unreleased]

### Added
- Cursor pagination for /orders endpoint

## [1.5.0] - 2026-05-01

### Added
- New checkout flow (#123)

### Fixed
- Login race condition (#456)

### Changed
- Updated React to 19

### Deprecated
- /v1/users — use /v2/users

### Removed
- ...

### Security
- Updated dependencies
```

→ semantic-release 가 자동 생성 가능.

### CONTRIBUTING.md
```markdown
# Contributing

## Setup
[link to README setup section]

## Workflow
1. Fork & clone
2. Create branch: `feat/your-feature`
3. Commit (conventional commits)
4. Push & open PR
5. Address review feedback
6. Squash merge

## Code style
- Run `yarn lint` and `yarn format` before push
- Husky pre-commit hooks enforce this

## Tests
- Unit tests required for new logic
- Run `yarn test` locally

## Reporting bugs
- GitHub Issues with reproduction
```

### Onboarding doc
```markdown
# Engineering Onboarding

Welcome! This is for your first 2 weeks.

## Day 1
- [ ] Setup laptop
- [ ] Access: GitHub, Slack, AWS, Linear, etc.
- [ ] Read this doc
- [ ] Read [ARCHITECTURE.md](./ARCHITECTURE.md)
- [ ] Get coffee ☕

## Week 1
- [ ] Run app locally
- [ ] First small PR (typo / docs fix)
- [ ] Pair with engineer on a feature
- [ ] Read recent ADRs

## Week 2
- [ ] Take a small task from backlog
- [ ] Shadow oncall
- [ ] Attend retro

## Resources
- [Slack channels](#)
- [Wiki](#)
- [Tooling](#)
```

### Docs review
```
Code review = code 만 X.
Documentation review = docs 도.

PR template:
- [ ] Docs updated (README, API docs, ADR if applicable)
```

### Stale docs detection
```bash
# Last modified date
find docs -name '*.md' -mtime +180

# 또는 docs lint
markdown-lint docs/
vale docs/        # style guide
```

→ 6 months+ 안 변경 = 검토.

### Docs-as-code
```
- Markdown in git
- Same review process as code
- Version controlled
- Linked from code

→ Notion / Confluence 보다 좋음 (drift 적음).
```

### MkDocs / Docusaurus / Nextra (host)
```bash
# MkDocs
mkdocs new docs
mkdocs serve

# Docusaurus
npx create-docusaurus@latest

# Nextra (Next.js 친화)
```

→ docs/ → website 자동.

### Comments vs docs
```
Comment: "왜 이 줄"
Docs: "왜 이 system / flow"

코드 안 = 작은 why
Docs = 큰 why + how
```

### Living docs
```
README 의 "How to deploy" = step
실제 deploy = 같은 step

→ 다르면 docs 업데이트.
"Code 가 truth" 가 아닌 "Code + docs 가 truth".
```

### Internal vs public
```
Internal: 자세한 — implementation, decision
Public: 사용자 — API, integration

다른 audience.
```

## 🤔 의사결정 기준
| Doc 종류 | 추천 |
|---|---|
| 새 프로젝트 | README + CONTRIBUTING |
| 기술 결정 | ADR |
| API | OpenAPI + Scalar |
| Runbook | Per service / per migration |
| 학습 | Tutorial |
| 깊이 이해 | Explanation |
| Reference | Auto-generated when 가능 |

## ❌ 안티패턴
- **Stale docs**: code 와 다름 — worse than 없음.
- **모든 거 README**: 큰 → 안 읽음. Split.
- **Comments 가 "what"**: code 가 보임.
- **No ADR**: 결정 잊혀짐.
- **No onboarding**: 새 사람 헛수고.
- **Notion + git docs 둘 다**: drift.
- **Docs review 없음 (code 만)**: stale.

## 🤖 LLM 활용 힌트
- README + ADR + runbook 3종 baseline.
- Diataxis 4 categories.
- Docs-as-code (markdown in git).
- 매 PR 가 docs 업데이트 검토.

## 🔗 관련 문서
- [[Productivity_PR_Template]]
- [[Productivity_Code_Review]]
- [[Productivity_Migration_Runbook]]