---
category: Unified
tags: [auto-consolidated, technical-documentation]
title: [[Documentation-Strategy|Documentation-Strategy]]
last_updated: 2026-05-02
---

# [[Documentation-Strategy|Documentation-Strategy]]

## 📌 Brief Summary
> "지식의 영속성 확보: 코드가 '어떻게' 작동하는지를 넘어, '왜' 그렇게 설계되었는지와 사용법을 명확히 기록함으로써 팀의 인지 부하를 줄이고 지능의 단절 없는 공유를 보장하는 전략적 관리 활동."

## 📖 Core Content
문서화 전략(Documentation-Strategy)은 정보의 가독성, 최신성, 유용성을 유지하기 위한 계획입니다.

1.  **4가지 문서 유형 (Diátaxis framework)**:
    *   **Tutorials**: 학습자 중심의 실제 따라하기 (Learning-oriented).
    *   **How-to Guides**: 특정 문제를 해결하기 위한 스텝 ([[goal|goal]]-oriented).
    *   **[[Reference|Reference]]**: API 규격 등 기술적 상세 정보 (Information-oriented).
    *   **Explanation**: 설계 배경과 개념적 논의 (Understanding-oriented).
2.  **왜 중요한가?**:
    *   팀원이 떠나도 지식이 유실되지 않으며, 새로운 팀원이 빠르게 온보딩할 수 있음. ([[Cognitive Biases|Cognitive Biases]] 중 지식의 저주 방지)

## ⚖️ Trade-offs & Caveats
- **과거 데이터와의 충돌**: 과거에는 두꺼운 '매뉴얼 책자 정책'이었으나, 현대 정책은 코드와 함께 살아있는 'Docs as Code 정책'과 검색이 용이한 'Wiki 기반 지식 기지 정책'으로 진화함(RL Update). (이 Obsidian Wiki가 그 정점)
- **정책 변화(RL Update)**: AI가 코드를 읽고 문서를 자동으로 초안 작성하거나, 문서만 보고 동작하는 코드를 생성하는 '상호 보완적 문서화 정책'이 개발 문화의 중심이 됨.

## 🔗 Knowledge Connections
- [[Concept Mapping|Concept Mapping]], [[클린 아키텍처 (Clean Architecture)|Clean-[[Architecture]]-TypeScript]], [[Knowledge synthesis|Knowledge synthesis]], [[Cognitive Biases|Cognitive Biases]], [[Analysis|Analysis]]
- **Modern Tech/Tools**: Markdown, Docusaurus, Read the Docs, Notion/Obsidian.
---

---

- [[Mermaid_Diagrams]]: 텍스트 기반 다이어그램 작성 기법.
- [[Knowledge_Management_Systems]]: 문서가 저장되고 검색되는 지식 인프라.
- [[README_Guidelines]]: 프로젝트의 첫인상을 결정하는 문서화의 시작점.


## 1. 개요
시스템 아키텍처 문서화는 복잡한 소프트웨어의 구조, 컴포넌트 간 상호작용, 설계 의사결정을 시각화하고 기록하는 청사진이다. 단순히 기술적 사양을 나열하는 것을 넘어, 다양한 이해관계자(개발자, 기획자, 운영팀 등)가 시스템의 비즈니스 가치와 기술적 구현을 일관되게 이해하도록 돕는 커뮤니케이션의 핵심 도구이다.

## 2. 다각적 시스템 뷰 (System Views)
효과적인 문서화를 위해 독자의 역할에 따른 전용 관점(View)을 제공해야 한다.
- **개념적 뷰 (Conceptual View)**: 비기술 직군을 위한 관점. 시스템이 제공하는 사용자 가치와 핵심 비즈니스 시나리오에 집중.
- **컴포넌트 뷰 (Component View)**: 개발자를 위한 관점. 모듈 간 의존성, 데이터 흐름, API 인터페이스 정의 및 경계 명시.
- **운영 뷰 (Operational View)**: 인프라 및 DevOps를 위한 관점. 서버 배치, 데이터베이스 스케일링, 보안 프로토콜 및 배포 환경 설명.

## 3. 핵심 방법론 및 도구
- **C4 모델 (C4 Model)**: 컨텍스트(Context), 컨테이너(Container), 컴포넌트(Component), 코드(Code)의 4단계 추상화 계층을 통해 시스템을 직관적으로 탐색.
- **다이어그램 코드화 (Diagrams as Code)**: Mermaid, PlantUML 등을 활용하여 텍스트로 다이어그램을 정의. 버전 관리 시스템(VCS) 친화적이며 유지보수가 용이함.
- **사용자 결과 중심 서술**: "쿠버네티스 도입"과 같은 기술 중심 나열이 아닌, "사용자 폭증에도 안정적인 속도 보장"과 같이 비즈니스 가치로 변환하여 기록.

## 4. 트레이드오프 및 주의사항
- **아키텍처 드리프트 (Architectural Drift)**: 코드는 변하지만 문서는 그대로인 현상. 이를 방지하기 위해 문서 생성을 자동화하거나 코드와 문서를 동일한 저장소에서 관리(Docs like Code) 권장.
- **상세화의 함정 (The God Diagram)**: 하나의 다이어그램에 너무 많은 정보를 담으면 오히려 가독성이 떨어짐. 추상화 수준을 분리하여 '줌인/줌아웃'이 가능하도록 구성.
- **문서 부채 (Documentation Debt)**: 낡은 문서는 없는 것보다 위험하다. 정기적인 업데이트 세션을 갖거나, 더 이상 유효하지 않은 문서는 과감히 아카이빙 처리.

## 🧪 검증 상태 (Validation)
- **정보 상태**: 검증 완료 (Verified)
- **출처 신뢰도**: A
- **검토 이유**: 시스템의 복잡성을 관리하고 팀 내 암묵적 지식을 명시적 자산으로 전환하기 위한 전문적인 문서화 표준 정립.