Ch10 문서자료

한 줄 정의

문서자료는 코드를 완성하기 위해 작성해야 하는 모든 부수적 텍스트(코드 주석 포함)이며, 작성자에게는 비용이 즉시 발생하지만 이득은 미래의 독자에게 미뤄져 늘 저평가되므로, 버전 관리·소유권·리뷰·폐기 같은 코드의 라이프사이클을 그대로 입혀 개발 워크플로에 녹여 넣어야만 조직 규모에 맞게 품질이 유지됩니다.

쉽게 말하면

문서자료는 집을 지으면서 벽 속 배선도와 배관도를 남겨두는 일 과 같습니다. 직접 지은 사람은 어느 벽 뒤에 전선이 지나고 어디에 수도관이 묻혔는지 머릿속에 다 있으니 굳이 도면을 그릴 이유가 없습니다. 도면을 그리는 건 지금 당장 내 시간만 잡아먹고 나에게 돌아오는 이득은 0입니다. 그런데 2년 뒤의 나, 혹은 다음에 이사 온 사람이 벽에 못 하나 박으려다 수도관을 뚫어버립니다. 도면의 비용은 작성자가 즉시 치르지만 이득은 앞으로 그 집에 사는 모든 사람 에게 시간을 두고 돌아갑니다. 테스트와 똑같은 구조이지만, 테스트는 그래도 작성자 본인에게 곧장 이득이 돌아오는 반면 문서자료는 그조차 잘 돌아오지 않아 더 푸대접받습니다.

여기서 멈추면 그냥 ‘도면 그리기 귀찮다’는 흔한 이야기입니다. 이 장의 진짜 핵심은 도면을 어디에 두고 누가 갱신하게 만드느냐 입니다. 구글의 실패작 GooWiki는 도면을 집과 동떨어진 창고(위키)에 모아둔 격이었습니다. 누가 벽을 옮겨도 창고의 도면을 고치는 사람이 없으니 90%가 몇 달째 아무도 안 보는 낡은 종이가 됐습니다. 성공한 방식은 정반대였습니다 — 도면을 그 설비 바로 옆 벽에 테이프로 붙여 두고(코드 옆 g3doc), “배선을 바꾸면 도면도 같은 작업으로 함께 고친다”를 리모델링 허가 절차(코드 리뷰)에 끼워 넣은 것입니다. 문서를 특별하게 따로 관리하려는 시도가 실패의 원인이었고, 코드와 한 몸으로 취급한 게 해법이었습니다.

왜 중요한가?

엔지니어가 코드를 작성·이용·유지보수하며 토로하는 대표적 불만이 바로 양질의 문서자료 부족입니다. ‘이 메서드에 어떤 부수효과가 있지?’, ‘이 약어는 뭘 줄인 걸까?’, ‘이 문서는 최신 내용을 담고 있나?’ — 구글 엔지니어라고 해서 다르지 않았습니다.

문제의 뿌리는 혜택의 비대칭 입니다. 양질의 문서자료는 코드와 API를 이해하기 쉽게 만들고 실수를 줄이며, 새 인력을 팀과 코드베이스에 안착시키는 노력을 크게 줄여줍니다. 그런데 이 혜택은 주로 후임자와 독자에게 돌아가고 작성자에게는 즉각적인 이득이 거의 없습니다. 테스트는 작성자에게 곧바로 보상이 돌아오지만, 문서자료는 선제적 투자에 가까워 나중까지도 명확한 혜택이 돌아오지 않기도 합니다. 그래서 다들 ‘덜 중요하다’고 여깁니다.

여기에 몇 가지 오해가 더해집니다. 많은 엔지니어가 글쓰기를 프로그래밍과 별개의 기술로 보고, 영어에 유창하지 않으면 좋은 문서를 못 쓴다고 지레 포기합니다. 또 도구 지원과 워크플로 통합이 부족해 작성 자체가 상대적으로 어렵고, 문서가 ‘유지보수할 대상이 하나 더 느는 일’로 느껴집니다.

이것을 방치하면 문서 품질은 조직의 성장과 반대로 떨어집니다. 틀린 내용을 바로잡을 수 있는 사람은 더 이상 그 페이지를 볼 일이 없고, 새로 들어온 사람은 뭔가 이상한 걸 발견해도 확인해줄 사람도 보고할 곳도 없습니다. 조직이 커질수록 문서 속 실수가 두드러지고 숨은 가정이 맞지 않는 일이 많아집니다. 결국 개발자 설문에서 가장 큰 불만으로 꼽히게 됩니다. 그래서 핵심은 ‘문서를 더 잘 쓰자’는 의지가 아니라, 저평가받는 작업이 저절로 굴러가도록 만드는 구조 입니다.

핵심 내용

문서자료를 코드처럼 취급하라

이 장 전체를 관통하는 단 하나의 원칙입니다. 문서자료도 결국 하나의 도구이자, 특정 작업을 완수하기 위해 사용하는 또 하나의 언어(보통 영어)입니다. 프로그래밍 언어처럼 규칙·구문·스타일이 있고, 일관되어야 하고, 명확해야 하고, 이해를 방해하는 오류를 피해야 합니다. 문법이 중요한 이유도 규칙 그 자체가 아니라 문체를 표준화해 독자가 헷갈리지 않게 하기 위함입니다.

그래서 문서자료에 코드의 라이프사이클을 그대로 입힙니다.

• 꼭 따라야 하는 내부 정책과 규칙이 있어야 합니다.
• 버전 관리 시스템에 등록해 관리합니다.
• 관리 책임자(소유자)를 명시합니다.
• 변경 시 (문서가 설명하는 코드와 함께) 리뷰를 거칩니다.
• 코드의 버그를 추적하듯 문제를 추적합니다.
• 주기적으로 평가(테스트)를 받습니다.

소유자가 없는 문서는 점점 낡아 유지보수가 어려워집니다. 반대로 소유권이 명확하면 문서 업데이트를 버그 추적 시스템과 코드 리뷰 도구 같은 기존 워크플로에 통합하기 수월합니다. 소유자가 다른 문서끼리 내용이 충돌하면 표준 문서(canonical doc)를 하나 지정 하고 나머지는 통합하거나 폐기 대상으로 돌립니다. 구글에서는 go/ 링크로 바로 찾히는 문서를 표준으로 취급하거나, 소스 코드와 관련 문서를 한 쌍으로 묶어 버전 관리에 함께 등록해 어느 문서가 표준인지를 알립니다.

사례 연구 — GooWiki에서 g3doc으로

작고 날렵하던 시절 구글의 정보 공유 수단은 사내 위키 GooWiki였습니다. 모두가 하나의 문서를 공유하고 누구나 갱신할 수 있는, 합리적으로 보이는 선택이었습니다. 하지만 커지면서 한계에 부딪혔습니다 — 책임질 소유자가 없어 페이지가 낡아가고, 추가 프로세스가 불분명해 중복 페이지가 생기고, 수평적 이름 체계로는 방대한 정보를 계층적으로 정리하기 어려웠습니다. (폐기 시점에 약 90%의 문서가 최근 몇 달간 아무도 읽거나 갱신하지 않은 상태였습니다.)

해법은 중요 문서를 소스 코드처럼 변경 추적 한 것입니다. 소유자를 지정하고, 소스 트리상 위치를 표준으로 정하고, 오류는 버그 추적 시스템으로, 갱신은 코드 리뷰로 처리했습니다. 마크다운을 표준 서식으로 도입해 HTML/CSS 없이 편집하게 했고, 문서를 코드 안에 삽입하는 g3doc 프레임워크로 소스와 관련 문서를 한 화면에서 나란히 보게 했습니다. 위키와의 가장 큰 차이는 새 프로세스를 만들지 않고 기존 개발자 워크플로에 녹였다 는 점입니다.

독자를 알자

엔지니어가 문서를 쓰며 범하는 가장 큰 실수는 자신만을 위해 쓴다 는 것입니다. 자신을 위해 쓰면 특정한 가정이 녹아들기 쉬운데, 실제 독자는 사내 모든 엔지니어부터 외부 개발자까지 상당히 다양합니다. 따라서 작성 전에 만족시켜야 할 주요 독자가 누구인지부터 알아내고 그 독자를 향해 써야 합니다.

다만 좋은 문서라고 해서 글을 훌륭하게 잘 쓸 필요는 없습니다. 독자는 여러분이 한때 서 있던 위치에 서 있습니다. 단지 지금 여러분이 가진 새 도메인 지식이 없을 뿐입니다. 그러니 그 도메인에 익숙한 누군가면 충분하고, 도메인을 떠나지 않는 한 문서는 계속 개선할 수 있습니다.

독자는 문서에 접근하는 방식에 따라 두 부류로 나뉘며, 각자에게 효과적인 전략이 다릅니다.

독자 유형	상태	효과적인 전략
탐색자(seeker)	원하는 걸 정확히 알고, 문서가 그 정보를 담고 있는지만 확인하고 싶음	일관성 — 코드 주석처럼 비슷한 포맷을 일관되게 적용해 빠르게 훑고 판단하게 함
배회자(stumbler)	무엇을 원하는지 정확히 모름, 어슴푸레한 아이디어만 있음	명료성 — 파일 맨 위에 개요/소개 절을 두어 코드의 목적을 설명하고, ‘이 문서가 적합하지 않은 독자’까지 알려줌

배회자를 위해 구글 문서 상당수는 ‘TL;DR: 구글의 C++ 컴파일러가 궁금한 게 아니라면 더 읽을 필요 없습니다’처럼 시작합니다. 또한 고객(API 사용자)이냐 제공자(팀원)이냐도 중요한 구분입니다 — 특정 설계를 선택한 이유 같은 구현 내막은 유지보수하는 팀원에게는 중요하지만 최종 사용자는 알 필요가 없으므로, API 설명이 아니라 설계 문서에 적어야 합니다.

문서를 '짧게' 쓰는 것이 유리하다

복잡한 주제는 전문가와 초보자 모두에게 설명해야 할 때가 많습니다. 짧게 쓰려면 때로는 모든 정보를 길게 담은 다음 간명하게 편집하고 중복을 삭제하는 과정을 거쳐야 합니다. 블레즈 파스칼의 ‘시간이 더 있었다면 편지가 더 짧아졌을 거예요’라는 말처럼, 짧고 명확하게 관리하면 전문가와 초보자를 동시에 만족시킬 수 있습니다.

문서자료 유형 — 하나의 문서는 하나의 목적

엔지니어는 다양한 문서자료를 작성하는데, 중요한 것은 종류가 다름을 알고 서로 섞지 않는 것입니다. 하나의 API가 두 가지 일을 하면 안 되듯, 하나의 문서가 여러 목적을 담으려 해서는 안 됩니다. (초기 구글 위키 페이지의 실패가 정확히 이것이었습니다 — 링크·개념·API 참조가 뒤섞여 목적이 하나가 아니었고, 너무 길어 아무도 다 읽지 못했습니다.)

유형	목적과 핵심
참조용 문서자료(코드 주석 포함)	가장 흔한 형태. 코드의 사용법을 설명. 단일 소스(코드 주석)에서 파생되어야 함
설계 문서	프로젝트 착수 전 승인받는 경량 ADR. 설계 목표·구현 전략과 대안들의 트레이드오프를 명시
튜토리얼	사전지식 없는 사람도 ‘Hello World’를 실제로 동작시키게 하는 단계별 안내
개념 설명 문서	참조 문서만으로 부족할 때 API/시스템의 개요를 보강. 명확성을 위해 완전성·정확성을 일부 희생
랜딩 페이지	다른 페이지로 향하는 ‘교통경찰’. 자세한 정보는 모두 링크로 대체

참조용 문서자료와 코드 주석

참조용 문서자료의 대표가 코드 주석이며, API 주석과 구현 주석으로 나뉩니다. API 주석에는 구체적 구현이나 설계 결정을 넣을 필요가 없고, 사용자가 작성자만큼 API를 잘 안다고 가정해서도 안 됩니다. 자바·파이썬·Go는 Javadoc·PyDoc·GoDoc 같은 프레임워크로 코드 주석에서 참조 문서를 뽑아냅니다. C++는 표준 도구가 없는 대신 헤더(.h)와 구현(.cc)이 나뉘어 있으니 헤더에 API 설명을 답니다. 구글의 Code Search가 코드 정의를 검색 결과 상단에 바로 보여줄 만큼 훌륭해서, 문서를 코드 정의와 함께 두면 찾기도 유지보수하기도 쉽습니다.

좋은 코드 주석의 형태는 다음과 같습니다.

파일 주석 — 거의 모든 코드 파일에 있어야 하며, 파일에 담긴 내용을 요약하고 주 쓰임새와 의도한 독자를 명시합니다.

// -----------------------------------------------------------------------------
// str_cat.h
// -----------------------------------------------------------------------------
//
// This header file contains functions for efficiently concatenating and appending
// strings: StrCat() and StrAppend(). Most of the work within these routines is
// actually handled through use of a special AlphaNum type, which was designed
// to be used as a parameter type that efficiently manages conversion to
// strings and avoids copies in the above operations.

클래스 주석 — 모든 공개 클래스(와 구조체)에 있어야 하며, 클래스 자신을 문장의 주어로 두고 어떻게 동작하는지 설명합니다.

// AlphaNum
//
// The AlphaNum class acts as the main parameter type for StrCat() and
// StrAppend(), providing efficient conversion of numeric, boolean, and
// hexadecimal values (through the Hex type) into strings.

함수 주석 — 자유 함수나 공개 메서드는 ‘무슨 일을 하는지’를 선언적 동사 로 시작해 설명합니다. 3인칭 서술형 동사(Merges, Deletes, Creates)로 시작하면 헤더 전체에 일관성이 생겨 탐색자가 첫 동사만으로 원하는 기능인지 빠르게 파악합니다.

// StrCat()
//
// Merges the given strings or numbers, using no delimiter(s),
// returning the merged result as a string.

Returns, Throws 같은 상용구 섹션을 강제하는 관례가 있지만, 그것이 꼭 필요하다는 근거는 약합니다. 사후조건·매개변수·반환값·예외는 서로 독립적이지 않으므로 한 문장에 자연스럽게 녹이는 편이 더 명확할 때가 많습니다.

// Creates a new record for a customer with the given name and address,
// and returns the record ID, or throws `DuplicateEntryError` if a
// record with that name already exists.
int AddCustomer(string name, string address);

튜토리얼 — 모든 단계에 고유 번호를

튜토리얼을 쓰기 가장 좋은 시점은 누군가 팀에 새로 합류했을 때입니다. 가벼운 편집기를 열고 따라 하면서 수행해야 하는 모든 것 을 적되, 어떠한 사전 설정·권한·도메인 지식도 가정하지 않습니다. 먼저 설정돼야 하는 게 있다면 앞부분 ‘사전 요구사항’ 절에 명시합니다. 그리고 독자가 수행하는 모든 단계 하나하나에 고유한 번호를 붙이되, 독자의 행위가 아닌 시스템 동작에는 번호를 달지 않습니다.

아래 ‘나쁜 튜토리얼’은 이 원칙을 어깁니다 — 4·5단계는 서버에서 일어나는 일이라 독자가 할 일이 없고(3단계의 부수효과로 부연해야 함), 6·7단계는 사실 같은 일입니다.

1. http://example.com 서버에서 패키지를 다운로드합니다.
2. 셸 스크립트를 홈 디렉터리에 복사합니다.
3. 셸 스크립트를 실행합니다.
4. 이제 foobar 시스템이 인증 시스템과 통신할 것입니다.   ← 독자가 할 일 없음
5. 인증이 완료되면 foobar가 'baz'를 실행시킬 것입니다.    ← 독자가 할 일 없음
6. 명령줄에서 SQL 명령으로 'baz'가 실행되는지 확인하세요.   ┐ 사실
7. CREATE DATABASE my_foobar_db;를 입력합니다.            ┘ 같은 일

‘개선된 튜토리얼’은 독자가 직접 수행할 동작만 번호로 매기고, 시스템 동작은 해당 단계의 설명으로 흡수하며, 입력/출력은 별도 줄(고정폭 글꼴)에 명시합니다.

1. http://example.com 서버에서 패키지를 다운로드합니다.
   $ curl -I http://example.com
2. 셸 스크립트를 홈 디렉터리에 복사합니다.
   $ cp foobar.sh ~
3. 홈 디렉터리에서 셸 스크립트를 실행합니다.
   $ cd ~; foobar.sh
   (이제 foobar가 인증 시스템과 통신하고, 완료되면 baz DB를 구동한 뒤 셸을 띄웁니다.)
4. 명령줄에서 SQL 명령을 실행하여 'baz'가 동작하는지 확인합니다.
   baz:$ CREATE DATABASE my_foobar_db;

문서자료 리뷰

코드가 모두 리뷰를 받듯 문서도 리뷰를 거쳐야 합니다(코드만큼 널리 시행되지는 못합니다). 효과적인 방식은 크게 세 가지이고, 각각 다른 측면에 집중합니다.

리뷰	누가	무엇을
기술 리뷰	주제 전문가, 주로 팀 동료	정확성 — 코드 리뷰 과정에서 함께 다룸
독자 리뷰	도메인을 잘 모르는 사람, 신규 합류자나 API 고객	명확성
작문 리뷰	테크니컬 라이터나 자원자	일관성

핵심은 단 한 명이라도 봐주는 게 안 봐주는 것보다 낫다 는 점입니다. 모든 리뷰를 정식 프로세스로 진행할 필요도 없습니다. 문서화가 엔지니어링 워크플로에 녹아 있으면 품질은 점차 개선됩니다.

사례 연구 — 표준이 된 '개발자 가이드'

거의 모든 문서를 공유 위키로 관리하던 시절에도 예외적으로 잘 살아남은 문서가 있었습니다 — 구글의 C++ 스타일 가이드입니다. 선임 엔지니어(스타일 중재자) 그룹이 암묵적으로나마 소유·관리했기 때문에 항시 좋은 상태를 유지했고, 모두에게 표준으로 인식되어 짝퉁이 생겨나지 않았습니다.

소스 코드와 함께 사는 문서는 소유권도 자동으로 정해지지만, ‘C++ 개발자 가이드’처럼 마땅한 단일 디렉터리가 없거나 API 경계를 넘나드는 정보는 소스와 독립된 전용 저장소에 주제별로 모아 버전 관리합니다. 이런 개발자 가이드는 API 경계를 넘나드는 주제를 일관되게 설명하는 데 능한 테크니컬 라이터가 관리하는 경우가 많습니다. 시간이 흐르며 경쟁·보충 문서들이 표준을 수용해 폐기되고, 결국 C++ 스타일 가이드는 『C++ 개발자 가이드』에 편입되었습니다. go/cpp로 검색하면 바로 이 가이드가 돌아오게 되면서 표준 문서의 권위가 날로 견고해졌습니다.

문서화 철학

누가·무엇을·언제·어디서·왜

대부분의 기술 문서는 ‘어떻게(HOW)‘만 답하다 보니 나머지 질문을 잊습니다. 처음 두 문단이 끝나기 전에 다음에 답하도록 시도하면 문서의 틀이 잡힙니다.

• 누가 — 대상 독자. 필요하면 ‘Secret Wizard 프로젝트에 새로 합류한 엔지니어를 위한 문서’처럼 명시합니다.
• 무엇 — 문서의 목적. ‘무엇’과 무관한 정보가 적혀 있다면 별도 문서로 옮기라는 신호입니다.
• 언제 — 생성·리뷰·갱신 날짜. 자동화가 없다면 작성일(혹은 최종 갱신일)을 직접 기입합니다.
• 어디에 — 문서가 존재할 장소. 설정 관련 정보는 버전 관리 시스템에, 이상적으로는 설명하는 소스 코드와 함께 둡니다. 설계 논의는 협업에 편한 구글 문서를 쓰되, 용도가 ‘논의’에서 ‘안정된 버전 기록’으로 기울면 버전 관리가 잘 되는 시스템으로 옮깁니다.
• 왜 — 독자가 무엇을 얻어가길 바라는지. 소개 부분에 명시하면 마지막 요약에서 그 목표를 달성했는지 확인할 수 있습니다 (설계 문서에서는 ‘왜’가 ‘어떻게’만큼 중요합니다).

시작·중간·끝과 의도적 중복

거의 모든 문서에는 시작·중간·끝이 있어야 합니다. 절이 하나뿐인 문서는 단 하나의 이야기만 하게 되는데, 실제로 그런 문서는 드뭅니다. 절을 추가하길 두려워하지 마세요 — 절은 내용 흐름을 논리적으로 나누고 독자에게 로드맵을 제시합니다. 짧기로 유명한 ‘금주의 C++ 팁’조차 처음 절에서 문제를, 가운데 절에서 해법을, 결론 절에서 핵심을 요약했습니다.

대부분의 엔지니어는 중복을 꺼리지만(좋은 일입니다), 문서에서는 중복이 유용할 때가 있습니다. 각 절의 도입 단락에서 핵심을 요약한 뒤 나머지에서 구체적으로 설명하면, 독자가 중요 내용을 이해하는 데 중복이 도움을 줍니다.

좋은 문서의 세 특징은 서로 충돌한다

좋은 문서는 완전성(completeness)·정확성(accuracy)·명확성(clarity)을 보이지만, 셋을 한 문서에 모두 담기는 어렵습니다. 더 ‘완전하게’ 만들수록 명확성이 떨어지기 쉽습니다 — 가능한 모든 사용법을 담으면 숲이 거대해져 길을 잃습니다. 그래서 결국 ‘좋은 문서’란 의도한 역할을 잘 수행하는 문서 이며, 하나의 문서에 둘 이상의 역할을 맡기지 않는 게 핵심입니다. 품질을 빠르게 높이는 방법은 독자가 필요로 하는 것에 집중하는 것이고, 대개 적은 것이 낫습니다.

문서 폐기와 신선도 보증 기간

낡은 문서는 낡은 코드처럼 문제를 일으킵니다. 본래 목적을 다한 문서는 폐기하거나 ‘폐기 대상’으로 표시하고(가능하면 최신 정보 위치를 알려주고), 내 소유가 아니더라도 ‘이 문서는 더 이상 유효하지 않아요’ 같은 댓글을 남깁니다. 아무 표식 없이 유효한 척 돌아다니는 것보다 훨씬 낫습니다.

구글은 문서에 신선도 보증 기간(freshness date) 을 붙입니다. 마지막 리뷰 날짜를 메타데이터로 기록해 두면, 가령 3개월간 갱신되지 않을 때 알림 메일을 보낼 수 있습니다. 버전 관리되는 문서라면 갱신 시 코드 리뷰를 거치므로, 수시로 점검할 수 있는 저렴한 수단이 됩니다.

<!--*
# Document freshness: For more information, see go/fresh-source.
freshness: { owner: `username` reviewed: '2019-02-27' }
*-->

테크니컬 라이터가 필요한 순간

구글은 한때 중요해 보이는 프로젝트마다 필요 여부와 무관하게 테크니컬 라이터를 배정했습니다. 부담을 덜어 속도를 높여주리라는 기대였지만 잘못된 가정이었습니다. 희소하고 특화된 자원인 테크니컬 라이터를 팀 하나에 붙이는 건 확장성이 낮고, 오히려 그 팀의 엔지니어들이 문서 작성에서 멀어져 의도와 반대 결과가 났습니다.

엔지니어링팀 대다수는 팀에 필요한 문서를 스스로 완벽하게 작성할 수 있습니다. 팀 안에서는 피드백 루프가 기민하고 도메인 지식과 가정이 명확하기 때문입니다. 테크니컬 라이터가 정말 필요한 경우는 API 경계를 넘나드는, 팀원 외 독자를 위한 문서 입니다. Foo 팀은 Foo에 필요한 문서는 잘 알지만 Bar 팀에 필요한 게 무엇인지는 모릅니다. 도메인에 익숙하지 않은 사람을 더 잘 대변하는 것 — 그래서 ‘이 프로젝트가 어디에 유용한가’에 관한 팀 내 가정에 의문을 품어보는 것이 테크니컬 라이터의 핵심 역할입니다.

비교 / 트레이드오프

참조용 문서 vs 개념 설명 문서

코드 주석을 문서 세계의 단위 테스트에 비유하면, 개념 문서는 통합 테스트에 해당합니다. 단위 테스트가 개별 함수를 정확히 검증하듯 참조 문서는 개별 API를 완전·정확하게 기술하고, 통합 테스트가 여러 모듈의 연계 동작을 보듯 개념 문서는 여러 API가 얽힌 큰 그림을 설명합니다.

관점	참조용 문서 (코드 주석)	개념 설명 문서
목표	정확성·완전성	독자의 이해 (명확성)
범위	벌어질 수 있는 모든 상황을 기술	일반적 쓰임에 집중, 드문 부수효과는 생략
위치	소스 코드 안 (단일 소스에서 파생)	별도 문서 (소스에 삽입할 표준 위치가 없음)
작성 난도	매일 작성, 비교적 쉬움	가장 어렵고 가장 기피됨

완전성 · 정확성 · 명확성

한쪽을 높이면	희생되는 것	그래서
완전성 (모든 사용법·부수효과 기술)	명확성 (숲이 거대해져 길을 잃음)	참조 문서는 완전성을, 개념 문서는 명확성을 택함
명확성 (복잡한 주제를 쉽게)	정확성 (드문 경우를 생략)	정확한 보완은 참조 문서가 담당

세 특징을 모두 만족시키려 애쓰는 대신, 그 문서의 역할이 무엇인지 정하고 거기에 맞는 특징을 택하는 것 이 핵심입니다.

내 생각

• 이 vault 자체가 이 장의 실증입니다. Obsidian 노트를 마크다운으로 git에 넣고 리뷰·커밋·Quartz 배포로 굴리는 구조가 곧 ‘docs as code’이고 g3doc의 개인판입니다. 신선도 보증 기간 아이디어는 /lint-vault의 stale 스캔으로 이미 부분 구현돼 있습니다.

• 설계 문서 = 경량 ADR은 vault의 Design Decision 템플릿과 정확히 같은 물건입니다. ‘설계 목표 + 대안 트레이드오프 명시’라는 정의가 그대로 ADR이므로, 실무에서 결정 기록을 남길 때 이 장을 근거로 삼을 수 있습니다.

• ‘하나의 문서는 하나의 목적’은 API 설계 원칙의 문서판입니다. README에 설계 의도·튜토리얼·API 레퍼런스를 다 욱여넣는 흔한 안티패턴이 바로 GooWiki 페이지의 축소판입니다. 단일 책임을 문서에도 적용하면 됩니다.

• 문서 리뷰를 코드 리뷰에 얹는 게 현실적인 유일한 강제 수단입니다. 문서만 따로 리뷰하는 프로세스는 지속되지 않으므로, 코드를 바꾸는 PR에 관련 문서 변경을 같은 diff로 묶고 리뷰어가 함께 보게 하는 것이 핵심입니다. 이게 ‘워크플로에 녹인다’의 구체적 실행입니다.

• 함수 주석의 ‘Returns/Throws 상용구 거부’는 바로 쓸 수 있는 팁입니다. 사후조건·반환·예외를 한 문장에 녹이는 편이 Javadoc 태그를 기계적으로 나열하는 것보다 탐색자에게 더 명확할 때가 많습니다.

관련 개념

• Ch03 지식 공유 — 문서자료가 지식 전파 채널로 기능하는 문화적 배경
• Ch08 스타일 가이드와 규칙 — 표준 문서의 대표 사례인 C++ 스타일 가이드와 문서자료용 스타일 가이드
• Ch09 코드 리뷰 — 문서 리뷰와 갱신이 올라타는 코드 리뷰 워크플로