2nd/10_Wiki/Topic_Programming/Coding/Productivity_Documentation.md

id, title, category, status, source_trust_level, verification_status, created_at, updated_at, tags, tech_stack, applied_in, aliases

id	title	category	status	source_trust_level	verification_status	created_at	updated_at	tags	tech_stack	applied_in	aliases
productivity-documentation	Documentation — README / ADR / Runbook	Coding	draft	B	conceptual	2026-05-09	2026-05-09	productivity docs vibe-coding	language applicable_to Markdown Engineering		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

# 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

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

Deploy

See DEPLOY.md

Architecture

[Brief overview, link to ADRs]

Contributing

See 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 (자동화)

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 (자동)

// OpenAPI spec → 자동 docs
// Scalar / Stoplight / Redoc / Swagger UI

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

Code comment 가이드

// ❌ "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

/**
 * 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)

# 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

# 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

# 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

# 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)

# 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