Architecture Documentation & Diátaxis

1. Overview

아키텍처 문서화와 디아탁시스(Architecture Documentation & Diátaxis)는 코드는 계속 진화하는데 문서는 한 달 만에 썩어버리는 개발 조직의 고질적 질병을 타파하고, 살아 숨 쉬는 설계도와 문서를 유지하는 정보 설계의 물리학을 해부합니다.

학습자는 화살표가 100개 얽혀 있어 그린 사람조차 일주일 뒤면 해독하지 못하는 거대 UML의 비극을 뜯어봅니다. 나아가 코드를 지도로 추상화하여 구글 맵스처럼 줌인/줌아웃하는 **C4 모델(Context, Container, Component, Code)**의 직관성을 장악합니다. 마지막으로, 기술 문서가 튜토리얼인지 레퍼런스인지 목적도 없이 뒤섞인 스파게티 텍스트를, 사용자의 니즈에 맞춰 4가지 사분면으로 칼같이 썰어내는 위대한 프레임워크인 **디아탁시스(Diátaxis)**와, "왜 우리가 이 기술을 선택했는가?"를 증명하는 ADR(아키텍처 결정 기록) 역량을 확보합니다.

2. Scope & Boundaries

In-Scope

• C4 Model: 소프트웨어 아키텍처를 추상화 수준에 따라 4단계로 나누어 그리는 시각적 언어.
• Diátaxis Framework: 기술 문서를 Tutorials, How-to guides, Reference, Explanation 4가지로 완벽히 분리하는 문서 아키텍처.
• ADR (Architecture Decision Records): 특정 기술(예: MongoDB vs MySQL)을 선택한 당시의 컨텍스트, 결정, 결과를 기록하는 이력 관리.
• Docs as Code: 마크다운(Markdown)과 Git을 이용해 코드와 함께 문서를 버전 관리하는 문화.

Out-of-Scope

• UML Class / Sequence 세부 문법: 화살표의 점선, 실선, 마름모 등 객체지향 설계의 구체적 표기법 $\rightarrow$ 본 문서는 전체 시스템 '구조' 문서화에 집중하므로 구체적 UML 문법은 배제함.
• API Swagger / OpenAPI 자동화: 코드에서 API 스펙 문서를 자동 생성하는 기술 $\rightarrow$ 08-04-02 RESTful API Design 영역으로 위임.

Boundaries

• C4 모델 vs UML: UML은 '클래스와 메서드'라는 미시적 세계(Microscopic)를 완벽하게 기술하는 데 특화되어 있습니다. C4 모델은 '시스템과 시스템', '컨테이너와 컨테이너'가 어떻게 통신하는지 숲(Macroscopic)을 보여주는 데 특화되어 있습니다. 아키텍처 문서는 C4로 숲을 그리고, 극도로 복잡한 특정 결제 로직 하나만 UML 시퀀스 다이어그램으로 그리는 상호 보완적 경계를 명확히 긋습니다.

3. Counterexample

• 빅뱅 다이어그램의 저주: 아키텍트가 회사의 모든 마이크로서비스 50개와 DB, 큐, 외부 API를 하나의 거대한 Visio 다이어그램에 구겨 넣었습니다. 화살표가 수천 개 교차하여 잉크 덩어리가 되었습니다. 신규 입사자에게 이 지도를 주자, 그는 지도를 보다가 멀미를 느끼고 결국 동료의 등 뒤에 서서 질문만 던집니다. 줌인/줌아웃(C4 모델) 없이 모든 것을 한 화면에 담으려다 가독성이 0에 수렴한 문서화의 폭망입니다.
• 스파게티 가이드 문서: "Redis 설치 및 활용법"이라는 사내 위키가 있습니다. 첫 문단은 Redis의 역사(Explanation)로 시작하다가, 갑자기 서버 설치 명령어(Tutorial)가 나오고, 갑자기 SET, GET API 파라미터 표(Reference)가 튀어나오더니, 마지막엔 클러스터 장애 복구법(How-to)으로 끝납니다. 독자는 자기가 원하는 정보를 찾기 위해 이 10페이지짜리 스파게티 문서를 처음부터 끝까지 다 읽어야 합니다. 정보의 목적을 분리하지 않은(Diátaxis 부재) 끔찍한 독자 학대입니다.

4. Prerequisites

• 시스템 아키텍처 기본 (Basic): 서버, DB, 외부 시스템의 관계. (07-01-01 Monolithic to MSA)
• 마크다운(Markdown) 및 형상 관리 (Basic): 텍스트 기반의 문서 작성과 Git 커밋.

5. Learning Map

6. Learning Topics

Basic

Core Topic 01: 완벽한 도면의 환상 (The Illusion of Perfect UML)

• Why to Learn: "문서가 없어서 문제"라는 말보다 "문서가 있는데 거짓말을 해서 더 문제"라는 현업의 비극을 깨닫고, 코드가 변할 때 같이 변할 수 없는 무거운 문서를 지양하는 태도를 갖추기 위함입니다.
• What to Learn:
  • Concepts: Documentation Decay (문서 부패), Heavyweight vs Lightweight Documentation, Diagram Comprehension, Docs as Code.
  • Skills: 변경에 취약한 '마우스로 그린 예쁜 그림(Visio, PPT)'을 버리고, PlantUML이나 Mermaid처럼 '코드로 그리는 텍스트 다이어그램'으로 전환하여 Git 커밋과 문서 수정을 동기화하는 파이프라인 설계.
• How to Learn:
  • 1단계: 썩어가는 문서: 1월에 3주를 들여 완벽한 아키텍처 다이어그램을 PPT로 그렸습니다. 2월에 코드가 수정되어 결제 서버가 1개 더 붙었습니다. 코딩은 1시간 만에 끝났지만, 그림 그리는 담당자가 퇴사해서 PPT 원본이 없습니다. 문서는 방치되고, 3월이 되면 이 문서는 거짓말(Decay)을 하는 독이 든 사과가 됩니다.
  • 2단계: 코드가 문서다 (Docs as Code): 그림을 마우스로 그리지 않습니다. 텍스트로 A -> B : 결제 요청이라고 마크다운 파일에 씁니다. 그러면 파이프라인(Mermaid 등)이 알아서 그림을 렌더링해 줍니다. 코드를 수정하는 개발자가 PR(Pull Request)을 올릴 때 텍스트 문서도 한 줄 고쳐서 같이 커밋하게 만드는, 엔지니어 친화적 문서화의 기저를 해부합니다.
• Implement: Mermaid vs GUI Drawing 유지보수 벤치마크. GUI(PPT): 아키텍처 변경 $\rightarrow$ 파일 열기 $\rightarrow$ 선 긋기 $\rightarrow$ 정렬 맞추기 $\rightarrow$ 이미지 캡처 $\rightarrow$ 위키 업로드 (소요 시간: 10분, 코드와 버저닝 불일치). Docs as Code(Mermaid): 코드 수정 중 README.md 열어 ServiceC 단어 하나 추가 $\rightarrow$ git commit (소요 시간: 10초, 코드와 버전 완벽 동기화).

Recommended

Core Topic 02: 구글 맵스 아키텍처, C4 모델 (C4 Model)

• Why to Learn: 비즈니스 경영진부터 신입 프론트엔드 개발자까지, 서로 다른 청중(Audience)에게 딱 맞는 수준의 줌인(Zoom-in) 도면을 제공하여 소통의 병목을 부수기 위함입니다.
• What to Learn:
  • Concepts: C4 Model (Context, Container, Component, Code), Zoom-in/Zoom-out, Abstraction Levels.
  • Skills: "우리 회사는 무슨 앱을 만들고, 외부 결제망(PG)과 어떻게 엮여 있는가?"를 Level 1 (Context) 다이어그램으로 그리고, "그 앱 안에는 모바일 앱, API Gateway, 결제 DB가 있다"를 Level 2 (Container)로 확장해 그리기.
• How to Learn:
  • 1단계: Level 1: System Context (지구): 기술 용어(AWS, Spring, MySQL)를 전부 뺍니다. 사람(유저)과 우리 시스템(박스 1개), 외부 시스템(카카오페이 박스 1개)만 그립니다. 사장님과 기획자를 위한 숲입니다.
  • 2단계: Level 2: Container (국가): 우리 시스템 박스를 깝니다. 그 안에는 '모바일 앱', '웹 프론트(React)', '백엔드 API(Spring)', 'DB(MySQL)'라는 컨테이너(서버 단위)들이 어떻게 데이터를 주고받는지 그립니다. 아키텍트와 인프라 엔지니어용입니다.
  • 3단계: Level 3: Component (도시): 백엔드 API 컨테이너를 하나 깝니다. 그 안에 'Security Component', 'Email Component', 'Payment Component'가 어떻게 엮여있는지 그립니다. 백엔드 개발자용입니다.
  • 4단계: Level 4: Code (건물): 거의 안 그립니다. 이 단계는 IDE(인텔리제이)가 코드를 보면 알아서 그려줍니다. 무지성으로 다 때려 넣던 UML을 버리고, 청중에 맞춰 추상화의 깊이를 4단계로 칼질하는 예술을 뜯어봅니다.
• Implement: C4 다이어그램 레벨 트랜지션 모사 (Mermaid). L1(Context): [Customer] -> [Ticket System] -> [Stripe PG]. L2(Container): [Ticket System] 내부를 Zoom-in $\rightarrow$ [Web SPA] -> [API Gateway] -> [Ticketing Microservice] -> [PostgreSQL]. 비기술자(L1)와 기술자(L2)가 동일한 문서를 보고 각자의 해상도에 맞춰 이해하는 추상화의 승리 시각화.

Practical

Core Topic 03: 4분면의 법칙, 디아탁시스 (The Diátaxis Framework)

• Why to Learn: "설치법, 원리, API 스펙"이 뒤섞인 쓰레기 문서를, 사용자가 문서를 읽는 '목적(배울 것인가 vs 일할 것인가)'에 따라 4가지로 완벽히 해체하여 독자의 길 잃음을 막기 위함입니다.
• What to Learn:
  • Concepts: Diátaxis Framework, Tutorials (Learning-oriented), How-to Guides (Goal-oriented), Reference (Information-oriented), Explanation (Understanding-oriented).
  • Skills: 쿠버네티스 사내 위키를 쓸 때, "10분 만에 Nginx 띄워보기"는 Tutorial 폴더로, "SSL 인증서 갱신하는 법"은 How-to 폴더로, "Pod의 생명주기 철학"은 Explanation으로 분류하여 리팩터링하기.
• How to Learn:
  • 1단계: Tutorials (학습, 튜토리얼): 뉴비를 위한 겁니다. 목적은 '성공 체험'입니다. 독자의 손을 잡고 A부터 Z까지 "이거 치세요, 저거 치세요" 멱살 잡고 끌고 갑니다. (예: 장고(Django) 10분 만에 블로그 만들기).
  • 2단계: How-to Guides (실무, 하우투): 이미 기본을 아는 실무자를 위한 겁니다. 목적은 '문제 해결'입니다. 서론 빼고 "A 에러 날 때 B 명령어 쳐라"라는 요리 레시피입니다. (예: 장고에서 Redis 캐시 붙이는 법).
  • 3단계: Reference (정보, 레퍼런스): 코딩하다가 까먹었을 때 찾는 사전입니다. 목적은 '정확한 스펙'입니다. 서술형 문장을 빼고 표(Table)나 코드 덩어리로만 채웁니다. (예: 장고 ORM 메서드 파라미터 표).
  • 4단계: Explanation (이해, 이론): 코드가 어떻게 도는 게 아니라, '왜 이따위로 만들었는지' 철학과 원리를 설명합니다. (예: 장고의 MTV 아키텍처 철학). 이 4개의 사분면이 섞이는 순간 문서는 독(Poison)이 된다는 위대한 정보 설계 철학을 해부합니다.
• Implement: Diátaxis 문서 리팩터링 시뮬레이션. 입력(Spaghetti): Redis Docs [역사설명 + 튜토리얼 + SET명령어표 + 캐시적용법]. 출력(Diátaxis):
  • /tutorials/first-redis.md (손잡고 이끌기)
  • /how-to/setup-cache.md (목적 달성 레시피)
  • /reference/commands.md (정확한 API 규격)
  • /explanation/persistence.md (AOF/RDB 저장 원리). 문서의 응집도(Cohesion)가 극대화되는 구조화 렌더링.

Advanced

Core Topic 04: 퇴사자의 유산, 아키텍처 결정 기록 (ADR)

• Why to Learn: "우리는 왜 3년 전에 RDBMS 대신 NoSQL을 선택했는가?"라는 질문에 아무도 대답하지 못해 시스템을 엎지 못하는 끔찍한 레거시의 저주를 방어하기 위함입니다.
• What to Learn:
  • Concepts: ADR (Architecture Decision Record), Context, Decision, Consequences, Immutable Records, Technical Debt Tracking.
  • Skills: "사용자 로그 저장소로 MySQL 대신 Elasticsearch를 도입한다"는 결정을 내릴 때, 당시의 컨텍스트(데이터 폭증), 대안(MongoDB), 최종 결정, 그리고 예상되는 후과(유지보수 학습 곡선 증가)를 마크다운 파일 1장(ADR)으로 기록하기.
• How to Learn:
  • 1단계: 잃어버린 맥락 (Context Lost): 신규 입사자가 코드를 봅니다. "아니, 왜 이렇게 비효율적으로 짰어? 당장 엎자!" 하고 엎었다가, 3년 전에 그럴 수밖에 없었던 특정 엣지 케이스(Edge Case)에 부딪혀 시스템이 붕괴합니다. 코드는 '어떻게' 동작하는지만 말해주지, '왜' 그렇게 짰는지는 말해주지 않기 때문입니다.
  • 2단계: ADR (기억의 박제): 아키텍처나 주요 스택을 바꿀 때 무조건 ADR 문서(001-use-elasticsearch.md)를 남깁니다. 여기에는 1. 당시의 상황(Context: 초당 로그 10만 건), 2. 결정(Decision: ES 도입), 3. 대가(Consequences: 돈이 많이 듦)를 적습니다.
  • 3단계: 불변의 역사책: ADR은 한 번 쓰면 수정하지 않습니다. 3년 뒤 ES를 버리고 다시 MySQL로 돌아간다면, 001번 문서를 고치는 게 아니라 045-migrate-back-to-mysql.md를 새로 씁니다. 팀의 기술적 의사결정이 진화해 온 역사를 증명하는 가장 위대한 공학적 일기장을 뜯어봅니다.
• Implement: ADR(Architecture Decision Record) 작성 템플릿 로직. Title: 012. 메인 DB를 MySQL에서 PostgreSQL로 마이그레이션. Status: Accepted (2024-05-10). Context: 공간 데이터(GIS) 쿼리 요구사항 폭증. MySQL의 공간 인덱스 한계. Decision: PostgreSQL + PostGIS 확장을 표준 DB로 채택한다. Consequences: [+] GIS 쿼리 10배 빨라짐. [-] 백엔드 팀 전체가 PgSQL 문법을 새로 배워야 하는 러닝 커브 발생. 이 종이 한 장이 3년 뒤 "왜 이런 미친 결정을 했지?"라고 묻는 후임자의 입을 다물게 하는 타임캡슐 역할 렌더링.

7. Terminology

8. References

Primary

• [P1] CS2023 - Software Engineering (SE) - Software Design and Architecture (Documentation)
• [P5] SFIA - Information Content Publishing (ICPM) - Technical Documentation

Secondary

• [Software Architecture for Developers] Simon Brown - The C4 model for visualising software architecture
• [Documenting Software Architectures] Paul Clements et al. - Views and Beyond

Industry

• [Diátaxis Framework] Daniele Procida - A systematic framework for technical documentation authoring
• [GitHub / AWS Prescriptive Guidance] - Architecture Decision Records (ADRs)
• [Mermaid.js] - Diagramming and charting tool

9. Final Checklist

Primary

• 개발자, 아키텍트, 비즈니스 기획자가 모인 회의에서, 모든 것을 한 화면에 우겨넣은 거대한 UML 대신 C4 모델의 Level 1(Context)과 Level 2(Container)를 분리하여 제시하는 추상화(Abstraction)의 커뮤니케이션 이점을 설명할 수 있는가?
• 아키텍처가 변경될 때마다 MS Visio나 PPT 파일을 열어 수정해야 하는 문서 부패(Documentation Decay)의 늪을, 텍스트 기반 다이어그램(Mermaid, PlantUML)과 Git(Docs as Code)을 활용해 어떻게 동기화하는지 증명할 수 있는가?

Secondary

• 사내 개발자 위키(Wiki)를 작성할 때, 처음 입사한 주니어를 위한 'Tutorial'과 장애 발생 시 시니어들이 따라야 할 'How-to Guide'의 작성 문체와 목적이 어떻게 달라야 하는지 디아탁시스(Diátaxis) 사분면을 적용하여 해부할 수 있는가?
• API 스펙과 파라미터 타입이 나열된 'Reference' 문서에, 비즈니스 배경지식이나 장황한 설명(Explanation)이 침투했을 때 독자(개발자)가 겪는 정보 검색의 인지적 과부하를 지적할 수 있는가?

Industry

• 3년 전 프로젝트에 GraphQL 대신 REST API를 선택했던 아키텍처 결정이 현재 트래픽 병목의 원인이 되었을 때, 과거에 남겨둔 ADR(Architecture Decision Record)의 Context와 Consequences 항목을 발굴하여 당시 결정의 타당성을 평가하고 새로운 ADR(전환)을 작성할 수 있는가?
• 마이크로서비스(MSA) 환경에서 50개의 레포지토리에 분산된 마크다운(Markdown) 문서와 ADR들을, CI/CD 파이프라인(예: Docusaurus, MkDocs)을 통해 하나의 중앙 집중형 정적 웹사이트(Developer Portal)로 렌더링하는 자동화 빌드를 설계할 수 있는가?