[G1-Sync] Manual knowledge update
This commit is contained in:
Antigravity Agent
@@ -0,0 +1,418 @@
|
||||
---
|
||||
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]]
|
||||
Reference in New Issue
Block a user