문서를 의심하라

운영 문서의 신뢰성에 대한 규칙을 하나 추가했다. 간단해 보이지만 팀 문화에 작은 변화를 주는 항목이다.

문제는 문서가 '지금'을 반영하지 않는다는 것

우리 팀은 기술 결정이나 운영 정책을 문서화한다. 당연히 해야 할 일이다. 그런데 현장에서 보면 문서가 현재 상황과 안 맞는 경우가 꽤 많다. 누군가 정책을 바꿨는데 해당 문서는 업데이트되지 않았거나, 특정 환경에서만 예외가 생겼는데 모두가 같은 문서를 따르다 보니 삽질하는 상황 말이다.

특히 "문서에 이렇게 나와 있으니까 우린 이대로 하면 되겠지"라는 마음가짐이 생기는 게 문제였다. 엔지니어링 판단이 멈추고 순응만 남는다. 변수가 빠르게 변하는 환경에서 문서는 그저 '참고 자료'일 수밖에 없는데, 마치 법령처럼 취급되고 있었던 것이다.

새로 추가된 규칙 세 가지

이번 항목에서는 명시적으로 세 가지를 규정했다.

세 번째가 핵심이다. "stale 자동정정"은 문서 버전 관리의 문제기도 하다. 예를 들어 A라는 정책이 변경되면, 그 문서를 참고하는 모든 곳에 알림을 보내거나 자동으로 배포하는 메커니즘이 필요하다는 뜻이다. 지금까지는 "변경됐으니 문서 업데이트해주세요" 요청이 있었다. 앞으로는 "변경 즉시 반영하고, 누가 언제든 검색했을 때 최신 상태를 보게 하라"는 의무가 생긴다.

왜 이게 중요한가

운영 문서는 명시적이고 원본성(source of truth)을 가져야 한다. 하지만 현실은 그렇지 않다. 실제로는 코드 자체가 진실이다. 데이터베이스 스키마, 배포 스크립트, 인증 로직 — 이들이 문서보다 항상 최신이다.

따라서 팀이 해야 할 일은:
- 문서를 '너무' 믿지 말되, 버려지지는 않게 유지하기
- 의심의 여지 있을 때는 코드/로그/실제 동작을 먼저 확인하는 습관
- 발견한 낡은 문서는 기다리지 말고 그자리에서 고치기

이렇게 하면 문서는 그 역할을 한다. 새로 온 사람의 온보딩 자료, 원칙의 기록, 토론의 장. 하지만 의존은 하지 않는다.

개인적 회고

이런 규칙을 명시적으로 쓴 이유는, 지금까지 암묵적이었기 때문이다. 몇몇 선임들은 자연스럽게 이렇게 행동했고, 신입들은 문서를 자세히 읽고 따랐다. 충돌이 생기기 전까지는 문제가 안 보였다. 그 분기점에서 "아, 우린 실측을 우선하는 문화를 명시해야 한다"고 깨닫고 문서화한 것이다. 작은 항목이지만 팀이 성장하는 과정을 기록하는 느낌이다.

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

• 모니터 쿠팡에서 보기 →
• 사무의자 쿠팡에서 보기 →
• 외장SSD 쿠팡에서 보기 →

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