코드는 6개월이면 낡지만, 좋은 문서는 몇 년을 산다
"코드가 곧 문서다"라는 말은 개발자 사이에서 오래된 클리셰입니다. 하지만 Atlassian의 2024년 개발자 생산성 조사에서 개발자의 **58%**가 "부족한 문서 때문에 업무 시간을 낭비한 적이 있다"고 응답했고, 평균적으로 주당 4.4시간을 문서 부재로 인한 비효율에 소비한다는 결과가 나왔습니다.
Stripe가 개발자 경험(Developer Experience) 분야에서 높은 평가를 받는 이유 중 하나는 API 문서의 품질입니다. Stripe의 개발자 문서는 "읽는 사람이 5분 안에 첫 번째 API 호출에 성공할 수 있어야 한다"는 원칙으로 설계되었으며, 이 문서 하나가 개발자 커뮤니티에서의 브랜드 가치에 기여한 바가 적지 않습니다.
기술 문서의 네 가지 유형
튜토리얼 (Tutorials)
학습 중심의 문서로, 독자를 단계별로 안내하여 특정 목표를 달성하게 합니다. "Django로 블로그 만들기", "Kubernetes 클러스터 설정하기" 같은 형태가 전형적입니다. Divio의 문서화 프레임워크에 따르면 튜토리얼의 핵심은 **학습(learning)**이며, 독자가 성공 경험을 얻는 것이 목적입니다.
좋은 튜토리얼의 조건은 명확합니다. 완료까지의 예상 시간이 제시되어야 하고, 각 단계에서 기대되는 결과가 명시되어야 하며, 중간에 막힐 수 있는 지점에 트러블슈팅 가이드가 포함되어야 합니다. 독자의 배경 지식 수준을 명시적으로 밝히는 것도 필수적입니다.
하우투 가이드 (How-to Guides)
특정 문제를 해결하기 위한 실용적 단계를 제공합니다. 튜토리얼과 달리 독자가 이미 기본 지식을 갖추고 있다고 가정하며, 유연성을 허용합니다. "React에서 인증 구현하기", "PostgreSQL 성능 최적화" 같은 형태로, **문제 해결(problem-solving)**이 핵심입니다.
레퍼런스 (Reference)
API 엔드포인트, 함수 시그니처, 설정 옵션 등 기술적 사실을 정확하게 기술하는 문서입니다. 완전성과 정확성이 가장 중요하며, 일관된 형식으로 작성되어야 합니다. 좋은 레퍼런스 문서는 검색과 탐색이 쉬워야 하며, 각 항목이 독립적으로 이해 가능해야 합니다.
설명 (Explanation)
시스템의 설계 배경, 아키텍처 결정의 이유, 개념적 이해를 돕는 문서입니다. RFC(Request for Comments)나 ADR(Architecture Decision Record)이 이 유형에 해당하며, **이해(understanding)**를 목적으로 합니다.
구조적 글쓰기의 원칙
1. 역피라미드 구조
신문 기사의 작성 원칙인 역피라미드 구조는 기술 문서에도 효과적입니다. 가장 중요한 정보를 먼저 제시하고, 세부 사항은 뒤로 배치합니다. 독자가 문서를 끝까지 읽지 않더라도 핵심 메시지를 파악할 수 있어야 합니다.
API 변경 공지를 예로 들면, "무엇이 변경되었고 언제 적용되는가?"를 첫 문장에 쓰고, "왜 변경되었는가?"를 두 번째 단락에, "마이그레이션 방법"을 세 번째에 배치하는 식입니다.
2. 능동태와 직접적 표현
"설정이 완료되어야 합니다"보다 "설정을 완료하세요"가 명확합니다. 수동태는 행위의 주체를 모호하게 만들어 독자의 혼란을 초래할 수 있습니다. 특히 절차를 설명하는 문서에서는 "~하세요" 형태의 직접적 지시문이 오해를 줄입니다.
3. 한 문단, 한 아이디어
각 문단이 하나의 주제만 다루어야 합니다. 첫 문장(Topic Sentence)에서 문단의 주제를 명시하고, 이어지는 문장들이 그 주제를 뒷받침하는 구조가 가독성을 극대화합니다. 문단이 5줄을 넘기면 분할을 고려하세요.
4. 구체적 예시 우선
추상적 설명만으로는 이해가 어렵습니다. 코드 예시, 스크린샷, 다이어그램을 적극 활용하세요. Stripe의 API 문서가 높은 평가를 받는 이유 중 하나는 모든 엔드포인트에 실행 가능한 코드 예시가 포함되어 있기 때문입니다.
5. 일관된 용어 사용
같은 개념을 여러 단어로 지칭하면 독자를 혼란에 빠뜨립니다. "사용자", "유저", "고객"이 모두 같은 의미라면 하나로 통일하세요. 프로젝트 차원의 용어 사전(Glossary)을 만들어 관리하는 것이 좋습니다.
문서 유형별 실전 가이드
API 문서 작성법
API 문서의 핵심은 "이 API로 무엇을 할 수 있는가?"에 대한 답입니다. 엔드포인트별로 HTTP 메서드, URL 패턴, 요청/응답 파라미터, 상태 코드, 에러 응답을 일관된 형식으로 기술합니다.
OpenAPI(Swagger) 스펙으로 API를 정의하면 문서를 자동 생성할 수 있어 유지보수 부담이 줄어듭니다. 다만 자동 생성 문서만으로는 부족하며, 사용 사례별 가이드와 퀵스타트를 별도로 작성하는 것이 좋습니다.
README 작성법
오픈소스 프로젝트의 첫인상은 README에서 결정됩니다. 프로젝트가 무엇인지(What), 왜 필요한지(Why), 어떻게 시작하는지(How)를 30초 안에 파악할 수 있어야 합니다.
구조는 프로젝트 한 줄 설명, 주요 기능, 빠른 시작(Quick Start), 설치 방법, 기여 가이드, 라이선스 순서가 표준적이며, 배지(CI 상태, 테스트 커버리지, 라이선스)를 상단에 배치하면 프로젝트의 건강 상태를 즉시 파악할 수 있습니다.
ADR(Architecture Decision Record) 작성법
ADR은 아키텍처 의사결정의 맥락, 결정, 결과를 기록하는 간결한 문서입니다. Michael Nygard가 제안한 표준 형식은 제목, 상태(제안/승인/폐기), 맥락, 결정, 결과의 다섯 섹션으로 구성됩니다. "왜 MongoDB가 아니라 PostgreSQL을 선택했는가?" 같은 질문에 6개월 후에도 답할 수 있게 해주는, 조직의 기억 장치입니다.
문서를 유지하는 것이 작성보다 어렵다
Google의 내부 조사에 따르면, 기술 문서의 50% 이상이 작성 후 6개월 이내에 코드와 불일치하게 됩니다. 문서의 정확성을 유지하려면 별도의 전략이 필요합니다.
코드와 문서를 동시에 업데이트하는 것을 코드 리뷰 체크리스트에 포함하고, 문서에 "마지막 검증 일자"를 표기하며, 자동화 가능한 부분(API 스펙, 코드 예시)은 CI/CD에서 생성되도록 설계하는 것이 실용적인 접근입니다.
개발자의 가치는 작성한 코드의 줄 수가 아니라, 해결한 문제의 영향력으로 결정됩니다. 좋은 문서는 그 영향력을 팀 전체로, 그리고 미래의 동료에게까지 확장하는 승수 역할을 합니다. 10줄의 문서가 100시간의 삽질을 방지할 수 있다면, 그것이야말로 최고의 레버리지입니다.
