Documentation Guide¶
이 문서는 source-repo에서 문서를 어디에, 어떤 형식으로, 어떤 검증 흐름으로 작성하는지 설명합니다. 개발자는 repo 전체에 대한 문서를 source-repo/docs/ 아래 Markdown으로 작성하고, app/package 전용 사용법은 각 디렉터리의 README.md에 둡니다.
1. 문서 작성 원칙¶
1-1. 문서는 code와 같은 change set에 포함한다¶
문서는 code, test, config와 같은 PR 흐름을 따릅니다. 코드 변경으로 사용법, architecture boundary, delivery 정책, package 소비 방식이 바뀌면 같은 PR 안에서 문서도 함께 수정합니다.
이 repo는 docs-as-code 방식을 사용합니다. 문서는 plain text Markdown으로 작성하고, Git versioning, issue, PR, CI 검증을 코드와 같은 방식으로 적용합니다.
1-2. Source repo는 문서를 작성하고 검증한다¶
이 repo의 책임은 문서 source를 관리하고 MkDocs strict build로 검증하는 것입니다. 문서 사이트를 실제로 서빙하는 일은 별도 docs repo와 infra/CD gate에서 다룹니다.
| 책임 | 담당 |
|---|---|
| Markdown 작성 | source-repo/docs/ |
| 문서 navigation 정의 | source-repo/mkdocs.yml |
| 문서 build와 contract 검증 | make docs/check |
| 문서 사이트 서빙 | 별도 docs repo |
| domain, ingress, hosting | 별도 docs repo와 infra/CD gate |
1-3. 독자의 다음 행동이 보여야 한다¶
좋은 문서는 독자가 다음에 무엇을 해야 하는지 바로 알 수 있게 씁니다. 배경지식이 부족한 개발자도 첫 문장, 표, command block만 훑어도 방향을 잡을 수 있어야 합니다.
문서를 쓸 때는 아래 질문에 먼저 답합니다.
| 질문 | 확인할 것 |
|---|---|
| 누가 읽는가 | 신규 개발자, package 소비자, release 담당자, app maintainer |
| 언제 읽는가 | local setup, PR 작성, package 설치, release, 장애 분석 |
| 무엇을 해야 하는가 | 읽기만 하면 되는지, command를 실행해야 하는지, 결정을 따라야 하는지 |
| 어디까지 다루는가 | source repo 책임인지, cd/infra/docs repo 책임인지 |
2. 문서 위치¶
2-1. Repo 전체 문서는 docs/에 둔다¶
Repo 전체에 적용되는 guide, architecture, workflow, delivery 정책은 source-repo/docs/ 아래에 둡니다. docs/는 MkDocs site의 source이며, mkdocs.yml의 nav로 사용자가 탐색합니다.
| 문서 성격 | 위치 |
|---|---|
| 처음 보는 개발자용 안내 | docs/getting-started/ |
| issue, branch, PR, 문서 작성 흐름 | docs/workflow/ |
| 제품 시나리오와 SaMD 품질 기준 | docs/product/ |
| architecture boundary와 contract | docs/architecture/ |
| architecture decision record | docs/architecture/decisions/ |
| 언어별 책임과 local command | docs/languages/ |
| CI/CD, release, Nexus, container | docs/delivery/ |
| 상세 reference와 보조 설명 | docs/reference/ |
2-2. README는 입구 역할만 맡는다¶
README는 repo를 처음 열었을 때 길을 안내하는 입구입니다. 길고 세부적인 판단 배경은 docs/로 옮기고, README에는 빠른 시작과 주요 문서 링크를 둡니다.
| 내용 | 위치 |
|---|---|
| Repo 전체 빠른 시작 | source-repo/README.md |
| Team guide와 설계 기준 | source-repo/docs/ |
| App 실행과 runtime contract | source-repo/apps/*/README.md |
| Package install과 public API 사용법 | source-repo/packages/*/README.md |
2-3. 새 문서는 navigation에 등록한다¶
사용자가 찾아야 하는 문서는 source-repo/mkdocs.yml의 nav에 등록합니다. MkDocs는 nav에 없는 Markdown도 build할 수 있지만, global navigation에 보이지 않으면 사실상 숨겨진 문서가 됩니다.
새 문서를 추가할 때는 아래를 함께 확인합니다.
mkdocs.yml의 적절한 section에 등록했는가- Home의 빠른 이동 표나 guide map에 링크가 필요한가
- README의 Main Documents 표에 추가할 필요가 있는가
- 기존 문서에서 새 문서로 이어지는 링크가 필요한가
3. 문서 유형¶
3-1. 문서 유형을 먼저 고른다¶
문서를 쓰기 전에 문서의 목적을 먼저 고릅니다. 이 guide는 Diataxis의 네 가지 문서 유형을 참고하되, repo 구조에 맞게 단순하게 적용합니다.
| 유형 | 목적 | 이 repo의 예 |
|---|---|---|
| Tutorial | 처음부터 끝까지 따라오게 함 | getting-started/demo-flow.md |
| How-to guide | 특정 일을 끝내게 함 | getting-started/local-development.md, delivery/package-consumption.md |
| Reference | 사실, contract, 규칙을 빠르게 확인하게 함 | reference/storage.md, glossary.md |
| Explanation | 왜 그런 구조인지 이해하게 함 | architecture/clean-architecture.md, product/samd-quality.md |
| ADR | 중요한 결정의 이유와 결과를 남김 | architecture/decisions/0001-*.md |
하나의 문서가 모든 역할을 하려고 하면 길고 무거워집니다. 처음 보는 개발자에게 순서를 안내해야 하면 tutorial, 이미 목적이 있는 개발자에게 절차를 알려야 하면 how-to guide, 판단 배경을 설명해야 하면 explanation, 오래 남을 결정을 기록해야 하면 ADR을 선택합니다.
3-2. App과 package 문서는 소비자 기준으로 쓴다¶
App README와 package README는 해당 디렉터리의 소비자가 바로 실행하거나 사용할 수 있게 씁니다. Repo 전체 정책이나 여러 언어에 걸친 delivery 기준은 docs/로 빼야 합니다.
| 대상 | 문서가 답해야 하는 질문 |
|---|---|
| App README | 어떻게 실행하는가, 어떤 env가 필요한가, health/readiness contract는 무엇인가 |
| Package README | 어떻게 설치하는가, public API는 무엇인가, 최소 사용 예시는 무엇인가 |
docs/ guide |
여러 app/package에 공통으로 적용되는 기준은 무엇인가 |
3-3. API reference는 자동 생성 문서와 분리한다¶
API reference는 docstring, typed public API, generated reference를 source of truth로 삼습니다. 사람이 쓰는 Markdown guide는 사용 맥락, 정책, 예시, boundary를 설명하고, 함수/클래스 목록을 손으로 복제하지 않습니다.
아직 자동 API reference가 준비되지 않았다면 빈 reference page를 유지하지 않습니다. 대신 issue로 남기고, 실제 생성 흐름이 준비된 뒤 nav에 추가합니다.
4. Architecture Decision Records¶
4-1. ADR은 중요한 결정의 이유를 남긴다¶
ADR은 Architecture Decision Record의 약자이며, architecture에 의미 있는 결정과 그 이유를 남기는 짧은 Markdown 문서입니다. ADR의 목적은 "무엇을 했는가"보다 "왜 그렇게 결정했는가"를 미래의 개발자가 이해하게 만드는 것입니다.
이 repo는 Nygard ADR처럼 작고 읽기 쉬운 기록을 기본으로 삼습니다. 큰 설계 문서 하나를 계속 키우기보다, decision 하나를 한 파일에 남기고 시간이 지나도 context, trade-off, consequence를 추적할 수 있게 합니다.
4-2. 모든 변경에 ADR을 쓰지는 않는다¶
ADR은 되돌리기 어렵거나 여러 영역에 영향을 주는 결정에만 씁니다. 일반 사용법, command, package 소비 방법, 작은 문구 변경은 보통 guide 문서나 README에 쓰면 충분합니다.
| ADR을 쓰는 경우 | 일반 문서로 충분한 경우 |
|---|---|
| app/package boundary를 바꾼다 | local 실행 command를 설명한다 |
| public API, contract, event schema를 바꾼다 | 특정 app README의 사용법을 보강한다 |
| storage, messaging, framework, registry 정책을 선택한다 | troubleshooting 문구를 추가한다 |
| security, availability, traceability 같은 non-functional requirement에 영향을 준다 | 기존 정책을 더 친절하게 설명한다 |
| CI/CD, release, artifact promotion 기준을 바꾼다 | broken link나 typo를 고친다 |
4-3. ADR은 decision log에 둔다¶
새 ADR은 docs/architecture/decisions/ 아래에 둡니다. 파일 이름은 순번과 lower-kebab-case 제목을 함께 사용합니다.
docs/architecture/decisions/
0001-use-trunk-based-development.md
0002-publish-guide-packages-to-guide-hosted.md
순번은 재사용하지 않습니다. 결정이 바뀌면 기존 ADR을 덮어쓰기보다 새 ADR을 만들고, 이전 ADR의 status를 Superseded로 바꿉니다.
4-4. ADR은 짧은 template을 쓴다¶
ADR은 한두 페이지 안에서 읽히는 것을 목표로 합니다. 이 repo에서는 아래 항목만 기본으로 사용합니다.
# ADR 0001: 결정 제목
## 1. Status
Proposed | Accepted | Superseded
## 2. Context
이 결정을 해야 하는 배경, 제약, trade-off를 설명합니다.
## 3. Decision
우리가 선택한 결정을 능동형 문장으로 씁니다.
## 4. Consequences
좋은 점, 나쁜 점, 중립적인 운영 영향을 함께 씁니다.
## 5. Links
- Issue:
- PR:
- Supersedes:
Context에는 사실과 제약을 씁니다. Decision에는 선택한 방향을 씁니다. Consequences에는 장점만 쓰지 말고 비용, 제한, 나중에 다시 봐야 할 조건도 함께 씁니다.
4-5. ADR은 PR에서 함께 검토한다¶
ADR은 코드와 같은 PR 흐름으로 들어옵니다. ADR이 Proposed 상태라면 PR discussion에서 결정 내용을 조정하고, merge 시점에 팀이 받아들인 결정은 Accepted로 둡니다.
이미 Accepted된 ADR은 과거 결정의 기록입니다. 새 사실이 생겨 방향을 바꿔야 하면 기존 ADR을 조용히 고치지 말고, 새 ADR을 만들고 이전 ADR을 Superseded로 연결합니다.
5. 작성 형식¶
5-1. Header는 세 단계까지만 사용한다¶
문서는 #, ##, ###까지만 사용합니다. 현재 위치를 쉽게 알 수 있도록 ## 1., ### 1-1. 형식으로 section number를 붙입니다.
# Documentation Guide
## 1. 문서 작성 원칙
### 1-1. 문서는 code와 같은 change set에 포함한다
세부 설명이 더 필요하면 header를 더 깊게 만들지 말고 표, 짧은 bullet, code block으로 나눕니다.
5-2. 파일 이름은 작고 예측 가능하게 쓴다¶
파일 이름은 lower-kebab-case를 사용합니다. 제목보다 검색과 링크 안정성을 우선합니다.
| 좋은 예 | 피할 예 |
|---|---|
documentation-guide.md |
DocumentationGuide.md |
package-consumption.md |
package consumption.md |
local-development.md |
local_dev.md |
5-3. 문단 첫 문장에 결론을 둔다¶
각 문단의 첫 문장은 결론이나 행동이어야 합니다. 배경 설명은 그 뒤에 둡니다.
| Before | After |
|---|---|
| 여러 상황에서 문서 위치가 달라질 수 있습니다. 그래서 혼동을 줄이기 위해... | Repo 전체 정책은 docs/에 둡니다. App/package 전용 사용법은 각 디렉터리의 README.md에 둡니다. |
| 이 명령은 여러 검증을 함께 수행합니다. | make docs/check는 문서 strict build와 contract 검증을 함께 수행합니다. |
5-4. 표는 비교와 선택에 사용한다¶
선택 기준, 책임 경계, command 목록은 표로 작성합니다. 긴 문장 안에 여러 책임을 넣으면 처음 보는 개발자가 읽기 어렵습니다.
표가 적합한 경우는 아래와 같습니다.
- app과 package 책임 비교
- dev와 release 정책 비교
- command와 사용 상황 정리
- registry endpoint와 credential 정리
5-5. 용어는 repo 안에서 일관되게 쓴다¶
낯선 용어는 처음 등장할 때 짧게 설명하고, 반복되는 용어는 Glossary에 추가합니다. 같은 개념을 문서마다 다른 이름으로 부르면 검색과 review가 어려워집니다.
예를 들어 package registry, hosted repository, group repository, proxy repository 같은 용어는 Nexus와 Package Consumption의 의미와 맞춰 씁니다.
6. 링크와 예시¶
6-1. 내부 링크는 상대 경로로 작성한다¶
같은 MkDocs site 안의 문서는 상대 경로로 링크합니다. 상대 경로는 base URL이나 hosting 위치가 바뀌어도 깨질 가능성이 낮습니다.
[Contribution Flow](contribution-flow.md)
[Nexus](../delivery/nexus.md)
README에서 docs/ 아래 문서를 링크할 때는 repo root 기준 경로를 사용합니다.
[Local development](docs/getting-started/local-development.md)
6-2. Command는 실행 위치를 알 수 있게 쓴다¶
Command 예시는 어느 디렉터리에서 실행하는지 독자가 추론하지 않게 작성합니다. 문맥상 source-repo에서 실행하는 명령이면 본문에 먼저 밝힙니다.
make docs/check
환경변수나 secret이 필요한 명령은 예시 값을 넣지 않습니다. 필요한 변수 이름과 발급 위치를 문장이나 표로 설명합니다.
6-3. Code reference는 실제 파일과 맞아야 한다¶
문서에서 code path, Make target, workflow name을 언급하면 실제 repo에 존재해야 합니다. 이름이 바뀌면 문서도 같은 PR에서 바꿉니다.
문서가 설명하는 대상이 아직 구현되지 않았다면 구현 예정이라고 쓰지 말고, issue로 남기거나 roadmap 성격의 문서로 분리합니다.
7. PR과 검증¶
7-1. 문서 변경은 PR에 포함한다¶
문서 변경도 일반 code change와 같은 contribution flow를 따릅니다. 작은 typo나 broken link는 issue 없이 hotfix PR로 처리할 수 있지만, architecture, workflow, release, security, clinical behavior에 영향을 주는 문서 변경은 issue나 PR description에 배경을 남깁니다.
PR description에는 최소한 아래를 적습니다.
| 항목 | 내용 |
|---|---|
| Summary | 무엇을 바꿨는가 |
| Context | 왜 지금 필요한가 |
| Validation | 어떤 command로 확인했는가 |
| Impact | clinical, contract, release, security 영향이 있는가 |
7-2. 문서 변경은 make docs/check로 확인한다¶
문서 변경 PR은 source-repo에서 아래 명령을 실행합니다.
make docs/check
이 명령은 MkDocs strict build뿐 아니라 repo에서 문서와 함께 관리하는 contract example, fixture, manifest 검증도 함께 수행합니다.
7-3. Navigation 변경은 strict build와 눈으로 확인한다¶
mkdocs.yml의 nav에 없는 파일은 build가 실패하지 않을 수 있습니다. 새 문서가 사용자에게 필요한 문서라면 nav와 Home 링크를 함께 확인합니다.
문서 링크가 깨졌거나 nav에 잘못된 파일을 등록하면 make docs/check에서 실패해야 합니다. 다만 문서가 논리적으로 좋은 위치에 있는지는 자동 검증만으로 알 수 없으므로, PR에서 Home, README, nav 흐름을 직접 확인합니다.
7-4. 문서 서빙은 이 repo에서 검증하지 않는다¶
이 repo는 문서를 빌드 가능한 Markdown source로 유지합니다. 문서 사이트의 domain, ingress, hosting, deployment는 별도 docs repo와 CD/infra 문서에서 확인합니다.
8. 참고 레퍼런스¶
8-1. 문서 구조와 작성 스타일¶
이 문서의 구조와 작성 기준은 아래 레퍼런스를 참고합니다.
| Reference | 이 guide에서 반영한 점 |
|---|---|
| Diataxis | tutorial, how-to, reference, explanation을 구분해 문서 목적을 먼저 고르는 방식 |
| Write the Docs: Docs as Code | Markdown, Git, issue, PR, automated tests를 문서에도 적용하는 방식 |
| MkDocs: Writing Your Docs | docs/ directory, mkdocs.yml, nav, relative link 기준 |
| Google developer documentation style guide | 개발자 문서에서 project-specific style과 clarity를 우선하는 기준 |
8-2. ADR 참고 자료¶
ADR 기준은 아래 레퍼런스를 참고합니다.
| Reference | 이 guide에서 반영한 점 |
|---|---|
| Michael Nygard, Documenting Architecture Decisions | 작고 versioned된 Markdown ADR, context/decision/status/consequences 구조, superseded 처리 |
| ADR GitHub organization | ADR은 decision과 rationale을 기록하고, ADR 모음은 decision log가 된다는 관점 |
| AWS Prescriptive Guidance: ADR process | structure, non-functional requirement, dependency, interface, construction technique에 영향을 주는 결정을 ADR 대상으로 보는 기준 |
| MADR | Markdown 기반의 가벼운 ADR template과 decision log 운영 방식 |