코드로 문서화

1) 건축 원칙

1. 하나의 진실의 원천. 코드 옆의 VCS에있는 문서, 다이어그램, 다이어그램, API 사양, 용어집.
2. 자동 품질 점검. 라이터, 철자, 링크 검사, 문서 테스트 코드 예.
3. 인공물로 조립. 도킹 사이트, CP/ebook, "내장 힌트" -릴리스 파이프 라인의 일부.
4. 수정 및 추적 성. Doc은 시스템의 동작을 변경하는 것과 동일한 PR을 규칙합니다. ADR은 커밋 바운드입니다.
5. 역할 별 가용성. 통합 업체를위한 공개/내부, 런북 및 통화 중 API 사양.
6. 수제 최소. 소스에서 테이블, 다이어그램, 종속 그래프, 코드 조각 생성.

2) 문서 유형 및 리포 구조

docs/
index. md architecture/
overview. md contexts/( C4, contexts, boundaries)
components/
data/
schemas/ (JSON Schema, Avro, Proto)
lineage/ (dataflow. md, dq-policies. md)
security/
threat-models/
key-management. md api/
openapi/ (OpenAPI. yaml)
asyncapi/ (.yaml)
grpc/ (.proto)
processes/
rfc/ (RFC-YYYY-XX-Title. md)
adr/ (ADR-0001-title. md)
runbooks/ (incident-.md)
playbooks/
sops/ (standard operating procedures)
product/
user-guides/
how-to/
faq/
i18n/
en/, en/, tr/# assets localization/
diagrams/ (Mermaid, PlantUML, Graphviz)
images/
_templates/ (RFC/ADR/Runbook templates)

• RFC-구현 전에 솔루션에 대해 토론합니다.
• ADR-고정 아키텍처 솔루션 (컨텍스트 → 솔루션 → → 대안의 결과).
• 런북/플레이 북-사건 및 작업에 대한 단계별 지침.
• 방법/FAQ-작업 → 단계 → 결과를 확인하십시오.
• API 사양-SDK 생성 및 도크의 소스로서 OpenAPI/AsyncAPI/Proto.
• 코드로서의 다이어그램-Mermaid/PlantUML/Graphviz/C4.

3) 스타일과 표준

단일 스타일 가이드 (톤, 용어, 제목 템플릿, 예).
표준 용어 (EN/RU), 별칭, 금지 된 제형을 갖는 용어집.
번호 및 참조: 영구 앵커, ADR/RFC/코드 간의 상호 참조.

yaml title: "Payment Service: Overview"
owner: "payments-team"
reviewers: ["platform", "security"]
last_review: 2025-10-15 tags: ["architecture","payments","pci"]

4) 집회 및 출판

• MkDocs (재료) -간단하고 편리하며 좋은 탐색 및 검색.
• Docusaurus-문서 버전 및 문서 + 블로그; MDX 구성 요소.
• Antora-대형 플랫폼을위한 모듈 식 문서.

yaml site_name: Platform Docs theme:
name: material features: [navigation. tabs, content. code. annotate, search. suggest]
plugins:
- search
- mermaid2
- mkdocs-awesome-pages-plugin
- macros nav:
- Review: index. md
- Architecture:
- Overview: architecture/overview. md
- Data: architecture/data/index. md
- API:
- REST: api/openapi/index. md
- Events: api/asyncapi/index. md

5) 코드로 다이어그램 및 다이어그램

mermaid sequenceDiagram participant C as Client participant G as API Gateway participant S as Service
C->>G: POST /orders
G->>S: createOrder()
S-->>G: 201 + order_id
G-->>C: 201 Created

@startuml
!include <C4/C4_Container>
Person(user, "User")
System_Boundary(system, "Platform"){
Container(api, "API", "HTTP")
Container(db, "DB", "Postgres")
}
Rel(user, api, "Uses")
Rel(api, db, "CRUD")
@enduml

OpenAPI/AsyncAPI가 사이트로 렌더링됩니다. SDK/클라이언트/예제가 생성됩니다.

6) 품질: 라인터 및 문서 테스트

• markdownlint-마크 다운 서식 규칙.
• 베일-스타일/용어/톤.
• 철자-철자 (RU/EN 사전).
• 링크 체크-외부/내부 링크, 앵커.
• Doctest/예-CLI/API 버전을 동기화하여 코드 스 니펫을 실행합니다.
• Schematest-OpenAPI/AsyncAPI/JSON Schema/Proto 유효성 검증.

yaml name: docs-ci on: [pull_request, push]
jobs:
lint:
runs-on: ubuntu-latest steps:
- uses: actions/checkout@v4
- run: npm i -g markdownlint-cli
- run: markdownlint "docs//.md"
- run: pipx run codespell docs          true
- run: pipx run linkchecker docs/site          true build:
runs-on: ubuntu-latest steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
- run: pip install mkdocs-material mkdocs-mermaid2-plugin
- run: mkdocs build --strict preview:
if: github. event_name == 'pull_request'
runs-on: ubuntu-latest steps:
- uses: actions/checkout@v4
- run: mkdocs build
- uses: actions/upload-pages-artifact@v3

python docs/snippets/calc. py def add(a,b):
"""Returns sum of a and b.

>>> add(2,3)
5
"""
return a+b

CI는 '파이썬 -m 도크 테스트 문서/스 니펫/calc. py '.

7) 프로세스: 노후화를위한 RFC/ADR/리뷰 및 SLA

RFC 흐름: 개시자 → 초안 사본 → 토론 → 결정 → 계획 → 구현 → 복고풍 사실.
ADR 흐름: RFC/실험에 대한 선택 + 참조를 간단히 수정합니다.
검토 절차: 출처- 'CODEOWNERS' + '의사 소유자. yaml '.
노후화를위한 SLA: 중요한 기사에는 '마지막 검토' 가 있으며 N 일 안에 검토를 위해 경고합니다.

markdown
ADR-0007: Select Event Log - Avro + Schema Registry
Date: 2025-10-31
Status: accepted
Context: the evolution of schemes without breaking consumers is required.
Solution: Avro + Schema Registry, backward compatibility.
Implications: tooling, compatibility tests, N services migration.
Alternatives: JSON Schema, Protobuf (rejected due to X/Y).

8) 현지화 (i18n) 및 다국어

현지화 전략: 소스 언어 (EN 또는 RU) → 'i18n/< locale>' 브랜치별 번역.
키 및 컨텍스트: 헤더/조각에 대해 "안정 ID" 를 저장합니다.
검사: 단계 '누락 키', 비동기화 경고.
로케일 스타일: 로컬 용어집, 잘못된 추적 용지, 로컬 UI 언어의 코드 예.

9) 제품 통합

내장 도움말 (인앱 문서): MDX 구성 요소, 컨텍스트 힌트.
릴리스 별 버전 지정: 태그/브랜치 문서/vX. 선택기 버전이있는 사이트 Y '.
섹션의 자동 생성: OpenAPI/AsyncAPI, GraphQL SDL, CLI '디렉터리'.
코드로서의 Changelog: PR 레이블에 의한 자동 생성 (feat/fix/docs/breaking).

10) 문서의 측정 및 관찰 가능성

문서 SLO: PR 후 빌드/게시 시간, 사이트 가동 시간, 문서 표시 시간.
아티팩트 적용 범위: ADR과의 서비스 공유, 예제와 엔드 포인트 공유, "건강 검진" 과 Runbooks 공유.
사용자 지표: 답변되지 않은 검색, 보기 깊이, 내장 프롬프트의 CTR.
품질: 린터 오류/1000 줄, "파손 된 링크", 오래된 기사의 비율.

11) 보안 및 개인 정보 보호

비밀과 PD는 요약에서 금지됩니다. 비밀과 마스킹을위한 린터.

SSO를 통한 내부 사이트 액세스; 공공 섹션이 분리되었습

수출 규칙: 내부 링크가없는 CP/아카이브, 기밀 문서의 워터 마크.
스크린 샷 위생: 자동 익명화 (mok data/blur).

12) 패턴

홍보 문서. 동작에 영향을 미치는 모든 변경 사항은 동일한 PR에서 도크를 업데이트

계약으로 템플릿. 도크 블랭크를 넣는 생성기를 통해 서비스/엔드 포인트/데이터 세트 생성.
코드로 차트. CI의 모든 그림-편집 가능한 소스, SVG/PNG 어셈블리.
문서 미리보기. PR의 사이트 미리보기에 대한 링크가있는 Bot 주석.
코드에서 링크를 도킹합니다. 사이트로 렌더링되는 소스 ('@ doc: adr/0007') 의 주석.

13) 반 패턴

코드 → 동기화되지 않은 버전이없는 wiki/Notion의 문서.
소스가없는 스크린 샷 → 자동으로 업데이트 할 수 없음.
구두 채팅 및 개인 파일에 대한 "비밀" 지식.
예와 불변이없는 제네릭 → 쓸모없는 페이지.
소유자의 부족과 '마지막 검토' → 노후화의 눈사태.
수동 조립 및 출판 → 깨지기 쉽고 드문 도크 릴리스.

14) 자동화 예

bash build. sh scripts/render-openapi. sh api/openapi/.yaml > docs/api/openapi/index. md scripts/render-asyncapi. sh api/asyncapi/.yaml > docs/api/asyncapi/index. md

bash linkcheck --config. linkcheck. yml site/

yaml
- name: Deploy Preview run: mkdocs build && npx serve -s site -l 5000 &
- name: Comment with URL uses: peter-evans/create-or-update-comment@v4 with:
issue-number: ${{ github. event. pull_request. number }}
body: "Preview: http ://preview- $ {{github. run_id }}.local"

15) 건축가 점검표

1. 코드 옆에 도크의 단일 저장소와 명확한 구조가 있습니까?
2. 설명 된 템플릿 (RFC/ADR/Runbook/How-To) 및 용어집?
3. 라인터에는 (markdownlint, Vale), 철자 확인, 링크 체크 및 문서 검사가 포함됩니까?
4. CI의 코드, 어셈블리와 같은 다이어그램 및 다이어그램?
5. API 사양 (OpenAPI/AsyncAPI/Proto) 이 검증되어 사이트로 렌더링됩니까?
6. 합병에 의한 PR 및 자동 게시를위한 조직 된 문서 미리보기?
7. 페이지의 노화 된 SLA (last _ review) 및 "소유자" 가 있습니까?
8. 메트릭: 적용 범위, 린터 오류, 고장난 링크, 검색 "제로" 쿼리?
9. 보안 정책: 비밀 금지, SSO, 워터 마크/수출?
10. 현지화는 지점에 의해 제어되고 누락되었는지 확인합니까?

결론

Docs-as-Code는 문서를 "포스트 팩트 노트" 에서 버전화, 테스트 및 제공되는 개발 아티팩트로 변환합니다. 이 접근 방식을 사용하면 코드 옆에 지식이 있고 변경 사항이 투명하며 사용자와 엔지니어가 필요할 때 최신 지침, 다이어그램 및 예제를받습니다. 이를 통해 운영 위험을 줄이고 온 보딩 속도를 높이며 플랫폼 전체의 솔루션 품질을 향상시킵니다.