문서가 코드를 따라가지 못할 때
문서 부채는 기술 부채보다 조용히 쌓인다. 갱신 전략 세 가지.
어디서 틀어지나
코드는 머지됐고 문서는 그대로다. 이게 반복된다.
- PR 에서 기능 바꿀 때 README 는 안 건드린다
- 배포 후 “나중에 정리”는 실행된 적 없다
- 문서가 틀렸다는 걸 새 팀원이 처음 온보딩할 때 발견한다
문서 부채는 기술 부채보다 조용히 쌓인다. 컴파일 에러가 없으니까.
지금 쓰는 전략
1. 코드 옆에 붙인다
별도 Wiki 에 쓰면 코드와 lifecycle 이 분리된다. 가능하면 docs/ 를 레포 안에. API 변경 PR 에 docs/ 수정이 없으면 리뷰에서 막는다. 규칙이 아니라 체크리스트 한 줄로 충분하다.
2. 갱신 트리거를 이벤트에 건다
“주기적으로 검토” 는 동작하지 않는다. 대신:
- 인터페이스 변경 → 해당 문서 담당자에게 코멘트 자동 할당
- 신규 입사자 온보딩 → 문서 읽으면서 틀린 곳 이슈로 남기기
- 장애 사후 보고 → 관련 runbook 날짜 확인
트리거가 없으면 갱신도 없다.
3. 살아있는 문서만 남긴다
6개월 이상 수정 없는 문서는 두 가지다. 진짜 안정된 것, 아니면 죽은 것. 구분하는 가장 빠른 방법: 해당 시스템 담당자에게 “지금도 맞냐” 물어보기. 틀렸으면 즉시 고치거나 삭제. 틀린 문서는 없는 문서보다 나쁘다.
다음 한 가지
다음 PR 에서 인터페이스 건드릴 때, docs/ 수정 없으면 셀프 블로킹.
🛒 이 글과 어울리는 추천 상품
위 링크는 쿠팡파트너스 활동의 일환이며, 일정액의 수수료를 제공받을 수 있습니다.