Architecture Documentation & Diátaxis

1. Overview

아키텍처 문서화 및 디아탁시스(Architecture Documentation & Diátaxis, ADD)는 보이지 않는 소프트웨어의 거대한 물리적 설계도를 형상화하고, 그 방대한 지식을 독자의 목적에 맞춰 가장 효율적인 수리적/논리적 경로로 전달하는 '지식 전달 공학'입니다.

학습자는 시스템의 뼈대를 나타내는 다양한 아키텍처 뷰(View) 모델과, 설계 결정의 역사를 기록하는 **ADR (Architecture Decision Record)**의 물리적 수순을 배웁니다. 특히, 현대 기술 문서의 정석인 Diátaxis 프레임워크를 통해 튜토리얼(학습), 가이드(수행), 설명(이해), 레퍼런스(정보)라는 4대 수리적 영역으로 지식을 하이브리드 분류하는 법을 익힙니다. 이를 통해 단순히 글을 쓰는 것을 넘어, 시스템이 물리적으로 어떻게 구동되고 진화하는지를 증명하고 전파하는 하이엔드 아키텍트의 소통 역량을 확보합니다.

2. Scope & Boundaries

In-Scope

• Architectural Views: 4+1 View, C4 Model을 활용한 시스템의 다차원적 물리 시각화
• Decision Records: ADR 작성법과 설계 선택의 수리적/논리적 배경 기록
• Diátaxis Framework: 학습(Tutorial), 기술(How-to), 개념(Explanation), 참조(Reference)의 물리적 구분
• Unified Modeling Language (UML): 클래스, 시퀀스, 컴포넌트 다이어그램의 매커니즘
• Documentation Pipelines: Docs-as-Code(Markdown, Git)를 통한 문서의 물리적 관리

Out-of-Scope

• 기획 수준의 사용자 요구사항SRS 명세 (09-01-02 REA 영역에서 분담)
• 소스 코드 내부의 개별 함수 주석 및 구현 상세 (09-01-04 Construction 영역에서 분담)

Boundaries

• ADD vs. REA: REA가 '필요한 기능'에 집중한다면, ADD는 그 기능을 담기 위해 선택한 '하드웨어/소프트웨어의 구조적 형태와 그 형태를 택한 논리'에 집중하여 경계를 구분합니다.

3. Counterexample

• 단순히 "그림 많이 그리기"라 설명하는 것은 ADD 학습이 아닙니다. 왜 C4 모델의 'Context' 다이어그램과 'Component' 다이어그램이 서로 다른 물리적 추상화 수준($Abstraction Level$)을 가져야 이해관계자의 혼란을 수리적으로 막을 수 있는지 증명할 수 있어야 하며, Diátaxis 원칙을 무시하고 튜토리얼 중간에 레퍼런스 수치를 나열하는 문서가 왜 독자의 논리적 관성을 물리적으로 파괴하는지 논증하지 못한다면 ADD의 가치를 이해하지 못한 것입니다.

4. Prerequisites

• Requirement Engineering & Analysis (Basic): 09-01-02의 요구사항 모델링 이해가 필수입니다.
• Design System Basics (Recommended): 시각적 위계 및 레이아웃 이해가 권장됩니다. (12-01-XX)

5. Learning Map

1. Skeleton Visualization: 보이지 않는 시스템의 골격을 비트와 관계선으로 물리적으로 투영합니다.
2. The Logic of Choice: 수많은 기술 후보 중 왜 '이것'을 택했는지 흔적(ADR)을 수리적으로 남깁니다.
3. Four Pillars of Knowledge: 정보를 읽는 사람의 상태에 맞춰 지식의 4대 영역(Diátaxis)으로 재배치합니다.
4. Living Blueprints: 시스템이 변할 때마다 문서도 하드웨어처럼 함께 진화하는 자동화된 관리 체계를 완성합니다.

6. Learning Topics

Basic

Core: 아키텍처 시각화와 표준 뷰 (View Foundations)

• Why to Learn: 전체 시스템을 한눈에 보지 못하면 고립된 부분 최적화라는 물리적 함정에 빠지기 때문입니다.
• What to Learn:
  • 4+1 View Model: 논리, 프로세스, 구현, 배치, 유스케이스 뷰의 물리적 역할
  • UML Strategy: 도메인 구조부터 패킷 흐름까지 핵심 다이어그램 선정 수순
  • Visual Abstraction: 너무 상세하거나 너무 막연하지 않은 적정 수치의 시각화 규칙
• How to Learn:
  • 복잡한 SNS 시스템을 보고 '논리 뷰'와 '배치 뷰'를 각각 그려보며, 하드웨어 장비와 코드 모듈의 물리적 매핑 차이 확인 실습
  • 다이어그램의 '복잡도 점수(노드 수/엣지 수)'를 계산하여 정보 전달력을 수리적으로 평가
• Implement: 시스템 개요를 입력하면 C4 Model의 Context 수준 다이어그램을 그려주는 기초 C4Generator

Recommended

Core: 설계 결정의 기록 ADR (Decision Records)

• Why to Learn: 1년 뒤 "왜 이렇게 짰지?"라는 질문에 당당히 수리적/논리적 근거로 대답하기 위함입니다.
• What to Learn:
  • ADR Structure: Title, Context, Decision, Consequences의 물리적 수순
  • Trade-off Analysis: A안과 B안 사이의 성능 vs 비용 수치적 비교 수록
  • Contextual History: 당시 하드웨어 제약이나 비즈니스 긴급성을 물리적으로 박제
• How to Learn:
  • 과거에 처리했던 'DB 선택'이나 '캐시 도입' 사례를 ADR 양식에 맞춰 재작성해보는 실습
  • 잘못된 결정을 내렸던 ADR을 분석하여, 어떤 수리적 근거가 누락되었었는지 물리적 역추적
• Implement: ADR 작성 시 필수 항목 누락을 체크하고 버전을 관리하는 ADRLinter

Practical

Core: 디아탁시스 지식 배치론 (Diátaxis Mechanics)

• Why to Learn: 아무리 좋은 지식도 찾는 목적과 다르게 섞여 있으면 시스템 구축을 방해하는 물리적 장애물이 되기 때문입니다.
• What to Learn:
  • Tutorials: 학습을 위한 따라하기식 물리 경험(Learning-oriented)
  • How-to Guides: 특정 과업 해결을 위한 직진 수순(Problem-oriented)
  • Explanation: 시스템 원리를 깊게 파헤치는 논리적 해석(Understanding-oriented)
  • Reference: 수치와 명세를 즉각 찾아보는 수리 장부(Information-oriented)
• How to Learn:
  • 뒤섞인 API 문서를 4가지 영역으로 가위질하여 재배치하고, 정보 도달 시간($Search Time$) 변화 수치 측정 실습
  • '학습용' 문서에서 수치 사전을 제거하여 독자의 물리적 인지 관성을 보호하는 필터링 훈련
• Implement: 특정 문구 덩어리가 Diátaxis의 어느 영역에 가까운지 확률적으로 분류하는 ContentClassifier

Advanced

Core: 문서 자동화와 Docs-as-Code (Doc Pipelines)

• Why to Learn: 코드는 변하는데 문서는 과거에 머물러 발생하는 '정보의 물리적 불일치'를 근절하기 위함입니다.
• What to Learn:
  • Static Site Generators: Hugo, Docusaurus 등을 활용한 문서 하드웨어 가공
  • Auto-generation: 코드(Swagger, TypeDoc)로부터 수리 명세를 뽑아내는 수순
  • CI/CD Integration: 코드 커밋 시 문서 빌드 및 배포의 물리적 결합
• How to Learn:
  • 깃허브 액션을 사용하여 마크다운 문서가 실시간 웹사이트로 물리적으로 변환되는 파이프라인 구축 실습
  • 코드의 변경분($Diff$)이 문서의 특정 영역을 무효화(Stale)하는 지점을 수리적으로 감지하는 연구
• Implement: 코드 변경 시 관련 문서의 업데이트 필요성을 알리는 DocStaleDetector

7. Terminology

8. References

Primary

• [P2] SWEBOK v4.0 - Software Design / Software Structure and Architecture (Architectural design) — Design standards.
• [P5] SFIA v9 - Software Engineering / Information content development — Communication skills.

Secondary

• [Documenting Software Architectures] Paul Clements — The standard for views.
• [The Diátaxis Framework] Daniele Procida — Official framework reference.

Industry

• [Joel on Software: Painless Functional Specifications] — Practical documentation advice.
• [AWS Architecture Icons & Diagrams Guide] — Cloud era visualization standards.

9. Final Checklist

Primary

• '4+1 View' 모델에서 각 뷰가 서로 다른 하드웨어/데이터 관점을 어떻게 수리적으로 보완하는지 설명 가능한가? (P2)
• 'ADR'이 미래의 개발자에게 기술적 관성($Technical Momentum$)을 어떻게 물리적으로 전달하는지 기술할 수 있는 가? (P2)

Secondary

• 'C4 모델'의 하위 단계로 내려갈수록 다이어그램의 '결합도($Coupling$)'가 수치적으로 어떻게 증가하는지 소통 가능한가?
• Diátaxis 프레임워크가 결여된 문서가 대규모 프로젝트의 온보딩 비용을 어떻게 수치적으로 가중시키는지 논증할 수 있는 가?

Industry

• 실무 아키텍처 리뷰($ATAM$) 시, 작성된 문서와 실제 코드 간의 물리적 괴리율을 측정하는 절차를 제안할 수 있는 가? (SFIA)
• Markdown 기반의 문서화 파이프라인에서 '이미지 자산'의 물리적 주소 관리를 자동화하는 수순을 분석할 수 있는 가?