문서화 문화가 팀에 미치는 영향

온보딩에 3주가 걸렸던 팀

올해 6월에 신입이 들어왔다. 온보딩 문서가 없었다. 기존 팀원들이 구두로 설명하고, Slack DM으로 링크를 보내주고, "이건 그냥 해보면 알아" 같은 말을 했다. 3주가 지나도 신입이 혼자 배포를 못 했다. 배포 절차가 문서화되어 있지 않았으니까. (정확히는 2년 전 Notion에 쓴 문서가 있었는데 현재 프로세스와 완전히 달랐다.)

그때 팀장이 선언했다. "이제부터 모든 프로세스를 문서화한다."

처음 한 달은 다들 싫어했다

PR을 올릴 때 관련 문서 업데이트를 같이 하라는 규칙이 생겼다. API를 추가하면 API 문서를 업데이트해야 하고, 배포 절차가 바뀌면 배포 가이드를 수정해야 한다.

처음엔 불만이 많았다. "코드 짜는 것도 바쁜데 문서까지 써야 하냐." 솔직히 나도 그 생각이었다. PR 하나 올리는 데 30분이 추가로 걸렸다. 하루에 PR을 세 개 올리면 1시간 반이 문서에 들어간다. 체감상 생산성이 떨어졌다.

석 달 지나니까 분위기가 바뀌었다

"이거 어떻게 하는 거야?"라는 Slack 메시지가 눈에 띄게 줄었다. 대신 "문서 보고 해봤는데 이 부분만 확인해줘"로 바뀌었다. 질문의 수준이 올라갔다.

측정해봤다. 문서화 도입 전 3개월 동안 "방법 문의" 성격의 Slack 메시지가 일평균 14.3건. 도입 후 3개월 동안은 일평균 5.7건. 60% 감소. (Slack 검색으로 세어봤다. 좀 원시적인 방법이긴 한데.)

두 번째 신입이 10월에 들어왔는데 온보딩에 8일 걸렸다. 첫 번째 신입은 3주였으니까 상당한 개선이다.

예상 못 한 부작용: 문서 관리 비용

문서가 쌓이기 시작하면서 새로운 문제가 생겼다. 오래된 문서가 현실과 안 맞는 경우. "이 문서 언제 업데이트된 거야?" "3개월 전인데..." 그러면 그 문서를 믿어야 하나 말아야 하나. 신뢰할 수 없는 문서는 문서가 없는 것보다 나쁘다. 잘못된 정보를 따라가니까.

그래서 매주 금요일 30분씩 "문서 정리 시간"을 만들었다. 근데 솔직히 이것도 부담이다. 매주 30분이면 월 2시간. 팀 6명이면 월 12시간. 1년이면 144시간. 사람 하나가 한 달 넘게 문서만 정리하는 셈이다. (이 계산을 하고 좀 충격받았다.)

그래도 돌아가고 싶진 않다

불만도 있고 비용도 있지만, 문서화 이전으로 돌아가자는 사람은 없다. "예전에 어떻게 했더라?"를 기억에 의존하던 때가 얼마나 비효율적이었는지 다들 체감하고 있으니까.

가장 큰 변화는 의사결정 과정이 투명해진 것. "왜 이렇게 결정했지?"가 ADR(Architecture Decision Record)에 남아있으니까, 6개월 전 결정을 되짚을 때 추측이 아니라 기록을 볼 수 있다.

후회하는 건 하나

처음부터 문서 템플릿을 만들어놨어야 했다. 각자 자유롭게 쓰라고 했더니 형식이 제각각이라 찾기가 어렵다. 어떤 사람은 Notion에, 어떤 사람은 GitHub Wiki에, 어떤 사람은 README에 썼다. 4개월 지나서야 "Notion으로 통일하고 템플릿을 쓰자"고 정했는데, 기존 문서를 마이그레이션하는 데 이틀이 날아갔다.

문서화는 좋다. 근데 "문서화를 어떻게 할 건지"를 먼저 정하는 게 문서화의 시작이다.