# Documentation Guide

## 1. 목적

이 가이드는 이 저장소의 기술 문서를 일관된 방식으로 작성하기 위한 기준입니다. 핵심 목표는 문서를 읽는 사람이 다음 질문에 답할 수 있게 만드는 것입니다.

- 왜 이 결정을 했는가?
- 대안은 무엇이었는가?
- 실제로 어떻게 동작하는가?
- 운영과 유지보수에 어떤 영향이 있는가?

## 2. 핵심 원칙

### 2.1 기본 서술 순서

모든 기술 문서는 가능하면 다음 순서를 따릅니다.

1. `Why`: 어떤 문제를 해결하려는가
2. `What`: 구조와 핵심 컴포넌트가 무엇인가
3. `How`: 내부 동작과 적용 방법이 무엇인가
4. `Result`: 결과, 트레이드오프, 남은 리스크가 무엇인가

### 2.2 좋은 문서의 기준

- 사용법보다 의사결정 근거가 더 중요합니다.
- 대안 비교가 있어야 합니다.
- 실제 겪은 문제와 해결 과정이 있어야 합니다.
- 코드와 설명이 분리되지 않아야 합니다.
- 운영 관점의 영향이 있으면 반드시 적습니다.

## 3. 문서 유형별 기준

이 repo 는 **ADR** + **트러블슈팅 / 런북** 두 축만 다룹니다. 일반 학습 노트나 인터뷰 준비, postmortem 같은 형식은 두지 않습니다 (개인 프로젝트 규모에 맞춤).

| 유형 | 목적 | 권장 스타일 | 반드시 포함할 것 |
|------|------|-------------|------------------|
| ADR | 기술 선택 근거 기록 | ThoughtWorks Lightweight ADR | Context, Options, Decision, Consequences |
| Architecture Doc | 구조와 동작 설명 | Google Design Doc | Scope, Goals, Diagram, Alternatives |
| Runbook | 운영 절차 문서 | Docs-as-Code | Preconditions, Steps, Verification, Rollback |
| Troubleshooting | 문제 해결 기록 | 기술블로그 스타일 | Symptom, Cause, Fix, Lesson |

## 4. 폴더 구조 원칙

### 4.1 상위 구조

`docs/` 아래를 목적별로 나눕니다.

- `docs/architecture/`: 시스템 구조와 설계 의도
- `docs/topics/`: 토픽별 ADR + 트러블슈팅 / 런북
- `docs/development/`: 로컬 개발 환경 / 실험 자료
- `docs/standards/`: 코딩 가이드 (언어 / 스프링 / DB / 웹 / 테스트 표준)
- `docs/examples/`: 위 standards 의 적용 예시
- `docs/templates/`: 재사용 템플릿 (ADR / 런북 / 트러블슈팅)

같은 기술이 두 영역에 동시에 나타날 수 있습니다. 이때 기준은 *주제* 가 아니라 *문서 목적* 입니다.

- `docs/topics/03-keycloak/`: Keycloak 아키텍처 ADR + 트러블슈팅
- `docs/development/keycloak/`: 로컬 실행 방법, realm import 파일

### 4.2 토픽 폴더 구조

특정 기술을 깊이 정리할 때는 `docs/topics/` 아래에 번호형 폴더를 사용합니다.

```text
docs/topics/
├── 02-clean-architecture/
│   ├── README.md
│   ├── 02-error-handling.md
│   ├── 02a-validation-deep-dive.md
│   └── 03-adr-boundary-refactoring.md
├── 03-keycloak/
│   ├── README.md
│   ├── 01-architecture.md
│   ├── 02-adr-keycloak-resource-server.md
│   ├── 03-claim-role-design.md
│   └── 04-adr-token-ownership-cleanup.md
└── 04-logging/
    ├── README.md
    ├── 01-architecture.md
    └── 02-runbook-log-correlation-and-dev-actuator.md
```

### 4.3 파일명 규칙

- 순서를 표현하는 문서는 번호를 붙입니다. 예: `01-architecture.md`
- ADR 은 `<n>-adr-<topic>.md` 또는 `adr-why-<topic>.md` 형태를 사용합니다.
- Troubleshooting / Runbook 은 제목만 봐도 목적이 드러나야 합니다. 예: `<n>-runbook-log-correlation.md`
- 각 토픽 폴더에는 반드시 `README.md` 를 둡니다.
- 다이어그램 산출물은 `docs/architecture/diagrams/` 폴더에 모읍니다 (PNG / `.drawio` / `.excalidraw`).

## 5. 문서 작성 체크리스트

문서를 마무리하기 전에 아래 항목을 확인합니다.

- 이 문서가 해결하려는 질문이 첫 화면에 드러나는가?
- 선택 근거와 대안 비교가 있는가?
- 다이어그램이나 흐름 설명이 있는가?
- 실제 코드나 설정 예시가 있는가?
- 실제 문제 사례 또는 운영 관점이 포함되었는가?
- 결과와 남은 리스크가 정리되었는가?
- 관련 README 에 링크를 추가했는가?

## 6. 문서별 최소 섹션 가이드

### 6.1 ADR

```markdown
# [선택한 결정]
## Context — 어떤 문제 / 제약이 있었는가
## Options — 어떤 대안들이 있었는가
## Decision — 무엇을 골랐는가
## Consequences — 결과 / 트레이드오프 / 남은 리스크
```

### 6.2 아키텍처 문서

- Context & Scope
- Goals / Non-Goals
- Architecture Overview (다이어그램 필수)
- Detailed Design
- Alternatives Considered
- Cross-cutting Concerns
- Result / Enforcement

### 6.3 트러블슈팅 문서

- 한 줄 요약
- 배경
- 증상
- 원인 분석
- 해결
- 교훈

### 6.4 Runbook

- Preconditions (시작 전 상태)
- Steps (실제 명령)
- Verification (완료 확인)
- Rollback (실패 시 복구)

## 7. 이 저장소에서의 권장 적용 방식

- 시스템 전체 구조는 `docs/architecture/` 에 둡니다.
- 토픽 ADR + 트러블슈팅 / 런북은 `docs/topics/` 에 누적합니다.
- 로컬 실행, 배포 보조 절차는 `docs/development/` 에 Runbook 템플릿으로 작성합니다.
- 신규 문서를 추가할 때는 템플릿을 복사해 시작하고, 해당 토픽의 `README.md` 를 함께 갱신합니다.
- 인프라 운영 문서 (k8s / vault / argocd / cert-manager 등) 는 이 repo 가 아니라 [Project-Infra](https://github.com/donghyeon-ka/Project-Infra) 에 둡니다.

## 8. 가장 중요한 원칙

가장 가치 있는 문서는 *"삽질 기록"* 입니다. 깔끔한 이론 요약만 있는 문서보다, 실제 문제를 어떻게 관찰하고 가설을 세우고 원인을 찾고 해결했는지를 남긴 문서가 더 오래 쓰입니다.