폐기된 줄 알던 추적 기능, 문서 현황 정정
목차
한동안 문서를 정리하다가 흥미로운 발견을 했다. 공용 문서에서 자세히 봐야 할 게 있다는 생각이 든 거다. site-pv 라는 추적 기능이 도큐멘테이션에는 '폐기/부활금지' 상태로 표기되어 있었는데, 실제로 시스템을 살펴보니 여전히 운영 중이었다. 무심코 지나칠 수 있지만, 이런 작은 오류가 팀 전체의 의사결정과 시스템 이해에 꽤 큰 영향을 미친다.
왜 이런 일이 생겼나
도큐멘테이션이 시간 지나면서 점점 레거시가 되는 건 피할 수 없는 문제다. site-pv 같은 기능은 과거에 정말 폐기 후보였거나, 어느 시점에 리뉴얼될 때 임시로 '부활금지' 상태로 마킹된 걸 그대로 놔뒀을 가능성이 높다. 그런데 담당 팀에서 몰래(?) 다시 개선하거나 운영 방식을 바꿔서 계속 써왔던 거다. 결과적으로 우리 문서는 중간에 덜 업데이트되어, 현재 상태와 괴리가 생겼다.
이게 무서운 이유는:
- 신규 프로젝트나 기능을 기획할 때 사람들이 문서부터 본다. "이건 폐기된 기능이니까 의존할 수 없다"고 판단하고 돌아간다.
- 의존성 정리나 레거시 제거 작업을 할 때 "이건 아무도 안 쓰는 거 맞다"고 착각할 수 있다.
- 온보딩할 때 새로 들어온 팀원들이 "이건 죽은 기능"이라고 이해하고, 실제로는 써야 할 상황에서도 못 쓴다.
정정과 함께 생각해본 것
이번 정정은 단순히 상태 하나를 바꾼 거지만, 그 뒤에 중요한 습관이 있어야 한다고 생각했다.
정기적인 도큐멘테이션 감사: 최소한 분기마다 주요 기능들의 상태를 실제 코드/운영 상황과 대조해야 한다. 특히 '폐기됨', 'deprecated', '보류 중' 같은 표지는 더 자주 확인해야 한다. 이런 상태는 의사결정을 크게 좌우하기 때문이다.
문서 오너십: 단순히 "코드가 바뀌면 문서도 바꿔라"가 아니라, 기능별로 '이 문서의 소유자가 누구인가'를 명확히 하는 게 좋다. 그럼 상태가 바뀔 때 누군가는 분명히 알 텐데, 그 사람이 문서까지 업데이트할 책임을 느낀다.
팀 커뮤니케이션: 코드 변경보다도, "이 기능의 상태가 변했다" 같은 소식은 문서 업데이트 -> 팀 공지로 이어져야 한다. 그래야 오래된 정보로 잘못된 판단을 하는 일이 줄어든다.
작은 수정, 큰 영향
이번 작업은 깊이 있는 리팩토링도, 새로운 기능도 아니다. 문서 한 줄을 고친 거다. 하지만 팀 리딩 관점에서 보면, 이런 작은 수정이 얼마나 중요한지 느껴진다. 도큐멘테이션은 단순한 참고 자료가 아니라 팀의 집단 기억이고, 그 정확성이 떨어지면 곳곳에서 작은 오해들이 쌓인다. 결국 의사결정 속도도 느려지고, 리소스도 낭비된다.
이런 발견이 있을 때마다 기록하고 팀에 공유하는 게 내 역할이라고 본다. 조직이 커질수록 문서의 신뢰도는 더 중요해진다.
🛒 이 글과 어울리는 추천 상품
*위 링크는 쿠팡파트너스 활동의 일환이며, 일정액의 수수료를 제공받을 수 있습니다.
댓글 0
첫 댓글 달아줘.