# 기술 문서 관리 (Technical Documentation Management)

## 목차
1. [개요](#1-개요)
2. [기술 문서의 종류와 체계](#2-기술-문서의-종류와-체계)
3. [문서화 전략 및 워크플로우](#3-문서화-전략-및-워크플로우)
4. [문서 관리 도구 및 방법론](#4-문서-관리-도구-및-방법론)
5. [고품질 문서 작성을 위한 가이드라인](#5-고품질-문서-작성을-위한-가이드라인)
6. [문서화 자동화 도구 활용법](#6-문서화-자동화-도구-활용법)
7. [문서 품질 측정 지표](#7-문서-품질-측정-지표)
8. [실제 운영 사례 (Case Study)](#8-실제-운영-사례-casestudy)
9. [유지보수 및 거버넌스](#9-유지보수-및-거버넌스)

## 1. 개요
기술 문서 관리란 소프트웨어 개발 및 시스템 운영 과정에서 발생하는 모든 기술적 지식을 체계적으로 기록, 저장, 갱신 및 공유하는 **전 과정의 체계적인 관리** 프로세스를 의미한다. 기술 문서 관리의 주된 목적은 지식의 파편화를 방지하고, 팀원 간의 정보 비대칭을 해소하여 개발 생산성을 높이며, 시스템 유지보수 시 발생할 수 있는 리스크를 최소화하는 데 있다. 잘 관리된 문서는 신규 입사자의 온보딩(On-boarding, 신규 구성원이 조직에 적응하는 과정) 기간을 단축시키고, 장애 발생 시 신속한 대응을 가능하게 하는 핵심 자산이 된다.

## 2. 기술 문서의 종류와 체계
기술 문서는 읽는 대상(Target Audience)의 전문성과 목적에 따라 구분되어야 한다. 대상에 맞지 않는 용어나 수준의 문서는 정보 전달 효율을 떨어뜨리기 때문이다.

| 문서 종류 | 대상 독자 | 목적 | 핵심 포함 항목 | 추천 도구 |
| :--- | :--- | :--- | :--- | :--- |
| **요구사항 정의서** | 기획자, 개발자, QA | 구현해야 할 기능과 제약사항 정의 | 기능 요구사항, 비기능 요구사항, 유스케이스 | Notion, Confluence |
| **설계 문서 (SDD)** | 개발자, 아키텍트 | 시스템 구조 및 구현 방법 설계 | 시스템 아키텍처, DB 스키마, API 명세, 시퀀스 다이어그램 | Markdown, Confluence |
| **API 문서** | 프론트엔드, 외부 연동 개발자 | 인터페이스 사용법 안내 | 엔드포인트, 요청/응답 파라미터, 에러 코드, 예제 코드 | Swagger, Redoc |
| **운영 가이드** | 인프라 운영자, SRE | 시스템 배포 및 장애 대응 | 배포 절차, 모니터링 지표, 백업/복구 방법, 트러블슈팅 가이드 | Wiki, GitBook |
| **사용자 매뉴얼** | 최종 사용자 | 제품 기능 활용 방법 안내 | 기능 설명, 단계별 튜토리얼, FAQ | GitBook, WordPress |

*참고: SDD는 Software Design Document의 약자로, 테스트 주도 개발(TDD)과 구분하여 표기함.*

## 3. 문서화 전략 및 워크플로우
문서는 한 번 작성하고 끝나는 것이 아니라, 소프트웨어의 생명주기와 함께 진화해야 한다.

### 3.1 문서 생명주기 (Lifecycle)
1. **작성 (Drafting):** 담당자가 템플릿에 따라 초안을 작성한다.
2. **검토 (Review):** 동료 검토(Peer Review)를 통해 기술적 정확성과 가독성을 검증한다.
3. **승인 (Approval):** 리드 개발자나 아키텍트가 최종 내용을 승인한다.
4. **배포 (Publishing):** 지정된 문서 저장소(Wiki, Git 등)에 게시하여 공유한다. (상세 내용은 [6. 문서화 자동화 도구 활용법](#6-문서화-자동화-도구-활용법) 참조)
5. **갱신 (Updating):** 코드 변경이나 정책 변경 시 즉시 수정한다.

### 3.2 최신성 유지 프로세스
문서의 '부패(Rotting)'를 막기 위해 다음과 같은 프로세스를 도입한다.
- **Definition of Done (DoD) 포함:** 기능 구현 완료의 정의에 '관련 문서 업데이트 완료'를 필수 항목으로 포함시킨다.
- **정기 문서 감사 (Doc Audit):** 분기별로 오래된 문서를 검토하여 최신화하거나 폐기한다.

## 4. 문서 관리 도구 및 방법론
팀의 규모와 개발 문화에 따라 적합한 도구를 선택해야 한다.

| 구분 | 도구 예시 | 장점 | 단점 | 적합한 사례 |
| :--- | :--- | :--- | :--- | :--- |
| **Wiki 기반** | Confluence, Notion | 진입장벽이 낮고 협업/편집이 매우 빠름 | 버전 관리가 어렵고 코드 연동성이 낮음 | 전사 공유 문서, 기획서, 가이드라인 |
| **Docs-as-Code** | MkDocs, Docusaurus, GitBook | Git 버전 관리 가능, CI/CD 연동, 마크다운 기반 | 비개발자의 접근 및 수정이 어려움 | API 명세서, 개발자 가이드, 기술 스펙 |
| **CMS 기반** | WordPress, Strapi | 강력한 권한 관리 및 콘텐츠 배포 제어 | 설정 및 유지보수 비용이 높음 | 대규모 외부 공개 문서 사이트 |

## 5. 고품질 문서 작성을 위한 가이드라인
일관성 없는 문서는 읽는 이에게 혼란을 준다. 표준화된 가이드라인 준수가 필수적이다.

### 5.1 작성 원칙
- **간결성:** 불필요한 수식어를 배제하고 명확한 문장(능동태)을 사용한다.
- **구조화:** 계층적 헤더(H1~H4)를 사용하여 정보의 위계를 잡는다.
- **시각화:** 수정과 유지보수가 용이하도록 Mermaid.js와 같은 **텍스트 기반 다이어그램(Diagrams as Code)** 도구 사용을 권장하며, 매우 복잡한 구조의 경우 Draw.io 등을 활용한다.

### 5.2 표준 마크다운 템플릿 예시
```markdown
# [기능명] 설계 문서

## 1. 개요
- **목적:** 이 기능이 왜 필요한가?
- **목표:** 달성하고자 하는 결과물은 무엇인가?

## 2. 상세 설계
### 2.1 프로세스 흐름
(여기에 시퀀스 다이어그램 또는 플로우차트 삽입)

### 2.2 데이터 모델 변경 사항
- 추가/변경되는 테이블 및 컬럼 정의

## 3. API 명세
- **Endpoint:** `POST /api/v1/resource`
- **Request:** `{ "key": "value" }`
- **Response:** `201 Created`

## 4. 고려 사항 및 제약 조건
- 성능 영향도, 보안 이슈, 예외 처리 방안
```

## 6. 문서화 자동화 도구 활용법
수동 문서화의 한계를 극복하기 위해 자동화 도구를 도입하여 휴먼 에러를 줄이고 효율을 높인다.

- **API 자동화:** Swagger(OpenAPI)나 Spring Rest Docs를 사용하여 코드에서 API 문서를 자동 생성한다.
- **다이어그램 자동화:** Mermaid.js를 사용하여 텍스트 기반으로 다이어그램을 생성하고 Git에서 렌더링한다.
- **문서 배포 자동화 (CI/CD 파이프라인):**
    - **워크플로우:** `Markdown 수정` $\rightarrow$ `Git Push` $\rightarrow$ `PR Review & Merge` $\rightarrow$ `CI Pipeline (Build/Lint)` $\rightarrow$ `Static Site Generation (SSG)` $\rightarrow$ `Cloud Storage/CDN 배포`
    - **예시:** GitHub Actions를 통해 마크다운 파일 수정 시 자동으로 Docusaurus 사이트를 빌드하고 AWS S3 또는 Vercel로 배포하는 파이프라인을 구축한다.

## 7. 문서 품질 측정 지표
문서가 실제로 도움이 되고 있는지 정량적/정성적으로 측정한다.

- **정량적 지표:**
    - **문서 조회수 및 체류 시간:** 어떤 문서가 가장 많이 참조되는가?
    - **문서 업데이트 빈도:** 최신 상태가 유지되고 있는가? (최근 3개월 내 수정 여부 등)
    - **온보딩 소요 시간:** 신규 입사자가 문서만으로 환경 구축을 완료하는 데 걸리는 시간.
    - **문서 커버리지:** 전체 기능 대비 작성된 문서의 비율.
- **정성적 지표:**
    - **피드백 루프:** 문서 하단 '도움이 되었나요?' 설문 조사 결과.
    - **질문 감소율:** 동일한 내용에 대한 반복적인 질문(Slack, Jira 등)의 감소 여부.

## 8. 실제 운영 사례 (Case Study)
**A사(마이크로서비스 아키텍처 도입 기업)의 사례:**
A사는 서비스가 50개 이상의 마이크로서비스(MSA)로 분리되면서 문서 파편화 문제를 겪었다. 각 팀이 서로 다른 Wiki 페이지를 사용해 정보 탐색에 많은 시간이 소요되었다.

- **해결책:** 'Docs-as-Code' 전략 도입. 모든 서비스 저장소 내에 `/docs` 폴더를 생성하고 마크다운으로 작성하게 함. 이를 중앙의 Docusaurus 사이트로 통합 배포하는 파이프라인 구축.
- **결과:** 코드 변경과 문서 수정이 동일한 Pull Request(PR)에서 이루어지게 되어 문서 최신성이 80% 이상 향상되었으며, 전사 통합 검색을 통해 타 팀의 API 명세를 찾는 시간이 획기적으로 단축됨.

## 9. 유지보수 및 거버넌스
문서의 양이 많아질수록 '쓰레기 정보'가 쌓이는 것을 방지하는 거버넌스가 필요하다.

- **문서 소유권(Ownership) 명시:** 모든 문서 상단에 작성자와 담당 팀을 명시하여 업데이트 책임 소재를 분명히 한다.
- **접근 제어(Access Control):**
    - **권한 분리:** 내부 기밀 문서(인프라 상세 설계, 보안 정책 등)와 외부 공개 문서(API 가이드, 사용자 매뉴얼)를 엄격히 구분한다.
    - **권한 관리:** 역할 기반 접근 제어(RBAC)를 통해 읽기/쓰기 권한을 관리하며, 외부 협력사에는 필요한 문서에 대해서만 읽기 권한을 부여한다.
- **아카이빙 정책:** 
    - **Deprecated:** 더 이상 사용되지 않지만 참고가 필요한 문서는 상단에 `[Deprecated]` 태그를 부착한다.
    - **Archived:** 완전히 폐기된 문서는 별도의 `archive` 폴더로 이동시키거나 삭제하여 검색 결과에서 제외한다.
- **명명 규칙(Naming Convention):** `[분류]_[서비스명]_[버전]_[날짜]`와 같은 일관된 파일/페이지 명명 규칙을 적용한다.