당신의 문서는 사용자에게 거짓말을 하고 있습니다
Source: Dev.to
직설적으로 말하자면: 현재 여러분의 문서가 사용자에게 거짓말을 하고 있을 가능성이 높습니다. 악의적이거나 의도적인 것은 아니지만, 그래도 거짓입니다.
세 달 전에 폐기한 그 엔드포인트? 아직도 활성 상태로 문서에 남아 있습니다. v2.3에서 이름을 바꾼 그 설정 플래그? 아직도 옛 이름이 표시됩니다. 제품이 진화하면서 47단계가 되는 그 “빠른 시작” 가이드?
매일 개발자들이 여러분의 문서를 보고, 더 이상 작동하지 않는 지침을 따라가며, 조용히 여러분의 제품이 망가졌다고 결론짓습니다. 버그를 신고하지도 않고, 불평도 하지 않으며, 그냥 떠납니다.
The Math Doesn’t Work
Documentation decays faster than you can maintain it.
Every feature ship, every API change, every UI update, every renamed variable creates potential doc drift. In a healthy engineering org shipping weekly? That’s 50+ potential documentation landmines per year per product.
Now look at your docs team. One person? Two? Part‑time contributors who’d rather be coding? The math never works.
Source: …
“릴리스 전에 문서 업데이트 할게요”
모든 팀이 이렇게 말합니다. 하지만 일관되게 실행하는 팀은 거의 없습니다.
왜일까요? 문서 업데이트는 기능 출시와 경쟁하기 때문입니다. 그리고 기능 출시가 항상 승리합니다.
CI는 병합 전에 코드 버그를 잡아냅니다. 테스트는 회귀를 잡아냅니다. 린터는 스타일 위반을 잡아냅니다.
문서가 뒤처지는 것을 잡아내는 것은 무엇일까요? 3개월 뒤에 들어오는 고객 불만? 시대에 뒤떨어진 안내를 읽으며 한 시간을 낭비한 사람의 지원 티켓? 그건 시스템이 아니라 희망일 뿐입니다.
The Bug Reframe
구식 문서를 버그로 간주하세요—“괜찮은 것”이나 “나중에 할게요”가 아니라.
문서가 한 말을 제품이 다르게 동작한다면, 이는 고객 경험에 대한 결함—즉 신뢰성 문제입니다. 버그는 추적되고, 우선순위가 매겨지며, 수정됩니다. 문서 드리프트는 누군가, 보통은 좌절한 고객이 눈치채기 전까지 계속 쌓여만 갑니다.
실제로 효과적인 방법
1. 작성만이 아니라 감지를 자동화하기
어려운 부분은 문서를 작성하는 것이 아니라 언제 문서를 업데이트해야 하는지를 아는 것입니다. 제품이 변경될 때, 현재 잘못될 가능성이 있는 문서를 표시해 주는 무언가가 있어야 합니다. 예시 알림:
“이 PR은 인증 흐름을 수정했습니다. 이 4개의 문서 페이지가 인증을 참조하고 있습니다.”
2. 문서를 코드와 동일한 워크플로에 두기
Docs‑as‑code는 저장 방식이자 워크플로 전략입니다. 문서가 동일한 레포에 존재하고, 동일한 PR에서 검토되며, 동일한 CI에서 테스트된다면, 코드와 같은 수준의 주의를 받게 됩니다—사람들이 갑자기 더 관심을 갖게 되어서가 아니라 시스템이 두 대상을 동등하게 취급하기 때문입니다.
3. “완료”에 문서 포함하기
기능은 문서가 업데이트될 때까지 배포되지 않습니다. 파괴적인 변경은 마이그레이션 가이드가 존재할 때까지 병합되지 않습니다. 이것은 제안이 아니라 게이트입니다.
도구 격차
코드 품질을 위해 우리는 린터, 포매터, 타입 체커, 테스트 프레임워크, 보안 스캐너, 의존성 감사 도구를 사용합니다.
문서 품질을 위해 대부분의 팀은 시간이 날 때 사람이 직접 읽는 것에 의존합니다. 이 격차 때문에 문서는 코드보다 더 빨리 부패합니다.
해결책은 더 많은 사람을 투입하는 것이 아니라, 코드에 이미 사용하고 있는 자동화 검사를 문서에도 적용하는 것입니다: 지속적인 검증, 체계적인 적용.
- 스타일 가이드 위반 → 자동으로 표시.
- 깨진 링크 → CI에서 감지.
- 용어 불일치 → 코드 스타일처럼 적용.
실제 비용
“우리 문서가 조금 오래됐어요”는 사소해 보이지만, 숨겨진 비용은 실제로 존재합니다:
- 지원 티켓 – 문서 때문에 발생한 문제에 대한 티켓
- 거래 손실 – 잠재 고객이 빠른 시작 가이드를 완료하지 못할 때
- 이탈 – 사용자가 제품이 작동하지 않는다고 판단할 때
- 엔지니어링 시간 – 문서가 처리했어야 할 질문에 답하는 시간
- 평판 손상 – “당신의 문서가 틀렸어요”라는 GitHub 이슈마다 발생
대부분 팀은 이러한 비용을 문서와 연결짓지 못합니다. 비용은 분산되고 지연되어 나타나지만, 시간이 지날수록 누적됩니다.
도전
10분 동안 다음을 수행하세요:
- 가장 중요한 사용자 여정을 선택하세요 (가입, 첫 API 호출, 기본 통합).
- 제품을 처음 보는 것처럼 자체 문서를 따라가 보세요.
- 지침이 실제와 맞지 않는 모든 부분을 기록하세요.
대부분의 팀은 가장 중요한 흐름에서 3‑5개의 문제를 발견합니다—사용자가 매일 겪는 문제들입니다. 이는 문서 문제라기보다 눈에 보이는 고객 경험 버그입니다.
내가 사용하는 것
전면 공개: 저는 자동화된 문서 검토를 위해 EkLine을 사용합니다. CI에서 실행되고, 스타일 문제를 표시하며, 깨진 링크를 잡아내고, 제품 변경이 문서에 영향을 미칠 때 알려줍니다.
이것이 유일한 옵션은 아닙니다. Vale는 자체 시스템을 구축하고 싶다면 훌륭합니다. 핵심은 도구가 아니라—코드에 적용하는 동일한 엄격함으로 문서를 다루는 것입니다.
무엇을 사용하든 첫 번째 단계는 동일합니다: 문서를 글쓰기 문제로 다루는 것을 멈추세요. 시스템 문제로 다루기 시작하세요. 글쓰기가 어려운 부분이 아니었습니다.
당신의 문서에서 가장 오래된 거짓은 무엇인가요? 진심으로 궁금합니다—댓글을 남겨 주세요. 판단하지 않겠습니다. 우리 모두 겪어봤으니까요.