당신의 문서가 사용자에게 거짓말을 하고 있다
Source: Dev.to
직설적으로 말하자면, 현재 여러분의 문서가 사용자에게 거짓말을 하고 있을 가능성이 높습니다. 악의적으로가 아니라, 의도적으로가 아니라, 그래도 거짓말을 하고 있습니다.
3개월 전에 폐기한 그 엔드포인트가 아직도 활성 상태로 문서에 남아 있나요? v2.3에서 이름을 바꾼 그 설정 플래그가 아직도 옛 이름을 보여주나요? 제품이 발전하면서 47단계가 된 그 “빠른 시작” 가이드는요?
매일 개발자들이 여러분의 문서를 열어 작동하지 않는 지침을 따라가고, 조용히 제품이 망가졌다고 결론짓습니다. 그들은 버그를 신고하지도, 불평도 하지 않습니다. 그냥 떠나버립니다.
수학이 맞지 않는다
문서는 유지할 수 있는 속도보다 더 빨리 부패합니다.
모든 기능 출시, 모든 API 변경, 모든 UI 업데이트, 이름이 바뀐 변수 하나하나가 잠재적인 문서 편차를 만들죠. 주간 배포를 하는 건강한 엔지니어링 조직이라면? 제품당 연간 50개 이상의 잠재적인 문서 지뢰가 됩니다.
이제 여러분의 문서 팀을 보세요. 한 명? 두 명? 코딩을 더 선호하는 파트‑타임 기여자? 수학은 절대 맞지 않습니다.
“릴리즈 전에 문서를 업데이트하겠습니다”
모든 팀이 이렇게 말합니다. 하지만 일관되게 실행하는 팀은 거의 없습니다.
왜일까요? 문서 업데이트는 기능 출시와 경쟁하기 때문입니다. 그리고 기능 출시는 언제나 승리합니다.
CI는 병합 전에 코드 버그를 잡아냅니다. 테스트는 회귀를 잡아냅니다. 린터는 스타일 위반을 잡아냅니다.
문서가 뒤처지는 것을 누가 잡아낼까요? 3개월 뒤에 들어오는 고객 불만? 오래된 안내 때문에 한 시간을 낭비한 사람의 지원 티켓? 그것은 시스템이 아니라 희망일 뿐입니다.
버그 재구성
구식 문서를 버그로 간주하세요—‘선택 사항’이나 ‘나중에 처리하자’가 아니라.
문서가 한 말을 제품이 다르게 동작한다면, 이는 고객 경험에 대한 결함, 즉 신뢰성 문제입니다. 버그는 추적되고, 우선순위가 매겨지며, 수정됩니다. 문서 드리프트는 누군가가 눈치채기 전까지, 보통은 불만을 가진 고객이 발견할 때까지 쌓여만 갑니다.
실제로 효과가 있는 방법
1. 작성만이 아니라 감지를 자동화하기
문서를 작성하는 것이 어려운 부분이 아니다. 문서를 언제 업데이트해야 하는지 알아내는 것이 어려운 부분이다. 제품이 변경될 때, 어떤 문서가 현재 잘못될 가능성이 있는지 표시해 주는 무언가가 있어야 한다. 예시 알림:
“이 PR은 인증 흐름을 수정했습니다. 이 4개의 문서 페이지가 인증을 참조하고 있습니다.”
2. 문서를 코드와 동일한 워크플로에 포함시키기
Docs‑as‑code는 저장소와 워크플로 전략을 동시에 의미한다. 문서가 동일한 레포에 존재하고, 동일한 PR에서 리뷰되며, 동일한 CI에서 테스트된다면, 코드와 같은 수준의 관심을 받는다—사람들이 갑자기 더 신경 쓰게 된 것이 아니라 시스템이 두 개를 동등하게 취급하기 때문이다.
3. “완료”에 문서 작업을 포함시키기
기능은 문서가 업데이트될 때까지 배포되지 않는다. 파괴적인 변경은 마이그레이션 가이드가 존재할 때까지 병합되지 않는다. 이것은 제안이 아니라, 반드시 지켜야 할 게이트이다.
도구 격차
코드 품질을 위해 우리는 린터, 포매터, 타입 체커, 테스트 프레임워크, 보안 스캐너, 의존성 감사 도구를 사용합니다.
문서 품질의 경우 대부분의 팀은 시간이 날 때 사람이 직접 읽는 것에 의존합니다. 이 격차 때문에 문서는 코드보다 더 빨리 부패합니다.
해결책은 더 많은 사람을 투입하는 것이 아니라, 이미 코드에 적용하고 있는 자동화 검사를 문서에도 적용하는 것입니다: 지속적인 검증, 체계적인 강제 적용.
- 스타일 가이드 위반 → 자동으로 표시.
- 깨진 링크 → CI에서 감지.
- 용어 일관성 부족 → 코드 스타일처럼 강제.
실제 비용
“우리 문서는 약간 오래되었습니다”는 사소해 보이지만, 숨겨진 비용은 실제입니다:
- 지원 티켓 문서가 만든 문제에 대해
- 거래 손실 잠재 고객이 빠른 시작을 완료하지 못할 때
- 이탈 제품이 작동하지 않는다고 결론 내린 사용자들로부터
- 엔지니어링 시간 문서가 처리해야 할 질문에 답하는 데 소요되는 시간
- 평판 손상 모든 “문서가 틀렸다” GitHub 이슈에서
대부분의 팀은 이러한 비용을 문서와 연결하지 않는다; 비용은 분산되고 지연되지만, 결국 누적된다.
도전 과제
10분 동안 다음을 수행하세요:
- 가장 중요한 사용자 여정을 선택하세요 (가입, 첫 API 호출, 기본 통합).
- 제품을 한 번도 본 적이 없는 것처럼 자체 문서를 따라가 보세요.
- 지침이 실제와 맞지 않는 모든 부분을 기록하세요.
대부분의 팀은 가장 중요한 흐름에서 3‑5개의 문제를 발견합니다—사용자들이 매일 겪는 문제들입니다. 이는 문서 문제라기보다 눈에 보이는 곳에 숨은 고객 경험 버그입니다.
내가 사용하는 것
Full disclosure: 저는 자동 문서 검토를 위해 EkLine을 사용합니다. CI에서 실행되며 스타일 문제를 표시하고, 깨진 링크를 잡아내며, 제품 변경이 문서에 영향을 미칠 때 알려줍니다.
It’s not the only option. Vale is excellent if you want to build your own system. The point isn’t the tool—it’s treating documentation with the same rigor we apply to code.
Whatever you use, the first step is the same: stop treating documentation as a writing problem. Start treating it as a systems problem. The writing was never the hard part.
당신의 문서에서 가장 오래된 거짓은 무엇인가요? 진심으로 궁금합니다—댓글을 남겨 주세요. 판단하지 않겠습니다. 우리 모두 그런 경험이 있죠.