문서는 항상 코드보다 한 발 뒤에 있다

문서가 낡았다는 걸 모르고 그대로 배포했다. 그게 문제였다.

환경변수 이름이 바뀐 지 3주가 지났는데, README는 구 이름을 그대로 들고 있었다. 신규 입사자가 그걸 보고 세팅하다가 반나절을 날렸다. 내가 바꿀 때 문서를 같이 안 고쳤으니까.

왜 문서는 항상 늦나

코드를 고치는 순간, 머릿속엔 이미 다음 일이 들어와 있다. 문서는 “나중에”가 된다. 그 나중이 영원히 오지 않는다는 걸 알면서도.

PR을 올리는 시점엔 코드 리뷰가 우선이라 문서 변경은 지적받지 않는다. 팀에서 리뷰 체크리스트에 “관련 문서 링크 첨부” 한 줄을 넣은 건 올해 2월이었는데, 그 전까지 3년간 문서 누락 PR이 통과된 게 수십 건이다.
문서를 고치는 행위 자체에 즉각적인 피드백이 없다. 코드는 테스트가 빨간불을 켜주지만, 문서는 틀려도 CI가 조용하다. 직접 해보니 이게 가장 무서운 부분이다 — 틀린 채로 오래 살아남는다.
문서가 어디 있는지 모를 때도 있다. Notion 한 곳, Confluence 한 곳, GitHub Wiki 한 곳. 세 군데에 비슷한 내용이 흩어져 있으면 아무도 책임지지 않는다.

실제로 써먹은 것: 문서도 diff를 남긴다

코드 PR에 문서 변경을 강제로 붙이는 방식을 시도했다. PR 템플릿에 체크박스 하나.

“이 변경으로 영향받는 문서가 있으면 링크를 적고 수정하거나, 없으면 N/A 표기.”

처음엔 형식적으로 N/A만 찍는 경우가 많았다. 그래도 괜찮다. 적어도 한 번은 생각하게 만들었다. 2~3개월 지나니까 링크가 진짜 붙어 나오기 시작했다. 월평균 문서 커밋이 기존 2건에서 11건으로 늘었다. 품질은 둘째치고, 일단 갱신 자체가 생겼다.

주인 없는 문서는 썩는다

“누가 받고 / 누가 백업” — README 첫 줄 원칙을 문서에도 적용했다.

서비스 아키텍처 문서에 “Owner: @mings, Last reviewed: 2026-03-14” 두 줄을 박아뒀다. 날짜가 오래됐으면 눈에 띈다. 이것만으로 방치 시간이 줄었다.
분기에 한 번, owner에게 슬랙 자동 알림을 보내도록 GitHub Actions로 짜뒀다. 스케줄은 UTC 기준으로. 0 9 * * 1처럼 적으면 서머타임 날 한 시간 어긋나는 걸 이미 한번 겪어봐서 UTC로 고정한다.
막상 해보면 owner 지정이 불편하다는 반응이 먼저 나온다. “내가 왜 혼자 다 관리하냐”는 거다. 그래서 owner는 최종 책임자가 아니라 “갱신 필요 여부를 가장 먼저 아는 사람”으로 의미를 다시 정의했다. 부담이 줄자 저항이 줄었다.

문서를 코드 옆에 두면 살아남는다

별도 위키보다 레포 안 docs/ 폴더가 더 오래 살아남는다. 체감상 그렇다.

코드를 수정하러 레포를 열었을 때, 같은 창에 문서가 보이면 고칠 확률이 올라간다. 반면 Confluence를 따로 열어야 한다면, 귀찮음의 문턱이 그냥 건너뛰게 만든다. docs/api-endpoints.md 파일을 코드베이스 안으로 옮긴 뒤로 해당 문서의 마지막 수정일 간격이 평균 42일에서 11일로 줄었다. 도구를 바꾼 게 아니라 위치를 바꾼 거다.

단, 레포 안 문서도 관리 안 하면 똑같이 썩는다. 위치만 옮긴다고 끝이 아니라는 것.

틀린 문서가 없는 문서보다 나쁠 수 있다

이건 좀 불편한 얘기다. 문서가 있으면 신뢰하게 된다. 틀린 정보를 확신 있게 따라가다 사고가 난다.

올해 초 온콜 중에 DB 페일오버 절차 문서를 보고 커맨드를 실행했는데, 그 문서가 6개월 전 인프라 변경 이후 한 번도 안 갱신된 거였다. 다행히 스테이징에서 먼저 실행해봤기 때문에 프로덕션엔 영향이 없었지만, 그날 이후 런북 상단에 “Last verified:” 필드를 추가했다. 날짜가 90일 이상 지난 런북은 초록색이 아니라 노란색으로 표시되도록 간단한 스크립트도 붙였다. 없는 문서보다 낡은 런북이 더 위험하다는 걸 그날 체감했다.

다음 한 가지

다음 글을 쓸 때, 이번에 “Last verified 필드 추가하기로 했다”는 게 실제 레포에 들어갔는지 한 줄로 확인한다.

🛒 이 글과 어울리는 추천 상품

위 링크는 쿠팡파트너스 활동의 일환이며, 일정액의 수수료를 제공받을 수 있습니다.