「코드가 곧 문서」라는 말은 듣기에 아름답지만, 현실은 6개월 후 자신이 작성한 API조차 이해하지 못하게 됩니다. 좋은 기술 문서는 단순한 보완 설명이 아니라 오픈소스 프로젝트의 채택 여부, API의 올바른 사용, 새 엔지니어의 2주 내 온보딩을 결정합니다. 이 글에서는 기술 문서의 분류부터 실용적이고 유지 가능한 문서 시스템 구축까지 안내합니다.
1. 기술 문서의 4가지 유형
Diátaxis 프레임워크는 기술 문서를 4가지 사분면으로 분류합니다：
| 유형 | 목적 | 전형적 예시 |
|---|---|---|
| 튜토리얼 | 초보자를 첫 성공 경험으로 안내 | 「5분 빠른 시작」 |
| How-to 가이드 | 특정 문제 해결을 위한 단계별 설명 | 「환경 변수 설정 방법」 |
| 레퍼런스 | 시스템의 완전한 기술 사양을 정확하게 설명 | API 엔드포인트 문서 |
| 설명（Explanation） | 설계 철학과 개념 배경 해설 | 아키텍처 결정 기록（ADR） |
2. README：프로젝트의 첫인상
합격한 README가 포함해야 할 내용：
- 한 문장 설명：이것이 무엇인지, 어떤 문제를 해결하는지
- 빠른 시작（Quick Start）：최소 3단계로 실행 가능하게
- 사용 예시：가장 전형적인 시나리오, 코드 포함
- 설정 설명：환경 변수, 설정 파일 형식
- 기여 가이드：버그 보고, PR 제출 방법
- 라이선스：MIT, Apache 2.0 등
Markdown 실시간 미리 보기：README 작성 시 Markdown 편집기로 실시간 미리 보기를 확인하고, 제목 계층, 표, 코드 블록의 표시를 검증한 후 GitHub에 붙여넣으세요.
3. Markdown 기술 문서 규범
제목 계층 규칙
#（H1）：문서당 하나만, 보통 문서 제목##（H2）：주요 섹션###（H3）：하위 섹션, H3보다 깊게 하지 않음- 레벨 건너뛰기 금지：H2에서 H4로 바로 건너뛰지 않음
링크와 이미지
- 원시 URL 사용 금지 — 의미 있는 앵커 텍스트 사용：
[설정 가이드](#configuration) - 이미지에 alt 텍스트 필수：
4. API 문서：개발자 경험의 핵심
필수 API 문서 요소：
- 엔드포인트 설명：HTTP 메서드 + 경로 + 용도
- 요청 파라미터：이름, 타입, 필수/선택, 기본값, 예시값
- 요청 예시：실제 값을 사용한 완전한 HTTP 요청
- 응답 형식：성공/실패 응답 구조, 모든 HTTP 상태 코드
- 에러 코드：모든 커스텀 에러 코드와 의미, 트러블슈팅
API 응답 예시 포맷팅：API 문서 작성 시 JSON 포맷터로 압축된 JSON을 읽기 쉬운 들여쓰기 형식으로 정리하여 문서 예시로 바로 사용하세요.
OpenAPI / Swagger 사양
RESTful API에는 OpenAPI 3.0 사양 채택을 권장합니다. Swagger UI 인터랙티브 문서를 자동 생성하여 사용자가 브라우저에서 직접 API를 테스트할 수 있습니다.
5. Docs as Code：문서를 코드처럼 관리하기
- 코드와 같은 PR에 문서 포함：API 동작 변경 시 같은 PR에 문서 업데이트 필수
- 링크 유효성 검사：CI/CD에서 문서의 깨진 링크 자동 스캔
- 예시 코드 테스트：튜토리얼의 코드 스니펫을 CI의 일부로 실행
문서 버전 차이 비교：업데이트 후 텍스트 비교 도구로 신구 버전의 차이를 빠르게 확인하세요. PR 설명에 변경 요약 첨부나 번역 버전 일관성 확인에 적합합니다.
6. 문서를 최신 상태로 유지하는 엔지니어링 메커니즘
- 문서 소유자：중요 문서마다 유지 담당자 지정, 분기별 검토
- 예시 코드 자동화 테스트：튜토리얼 코드 스니펫을 CI에 포함
- Changelog 습관：모든 릴리스에서 CHANGELOG.md 유지
- 「문서 대기 중」 표시：미완성 부분을 TODO로 표시 — 침묵보다 솔직함이 낫다
요약
- 기술 문서는 4가지：튜토리얼, How-to 가이드, 레퍼런스, 설명 — 레퍼런스만으로는 부족
- README는 3단계 이내로 실행 가능하게, 실제 값을 사용한 예시 필수
- API 문서 필수 요소：엔드포인트 설명, 모든 파라미터, 요청 예시, 응답 형식, 에러 코드
- Docs as Code：코드와 같은 PR, 같은 리뷰, 같은 CI가 문서를 지속적으로 업데이트하는 근본 메커니즘