4.6 문서화와 지식 메트릭

개요 및 동기

이 주제는 문서가 단지 어딘가에 기술적으로 존재하는지가 아니라 코드베이스를 안전하게 유지하는 데 필요한 지식이 실제로 문서화되어 있고 찾을 수 있는지 측정함으로써 4부를 마무리한다. 주제 3.5는 개발자 경험 관심사로서 소통과 협업을 다루었다. 이 주제는 코드 측면에서 같은 근본적인 문제, 즉 지식 가용성을 다룬다: 새로운 엔지니어, 혹은 낯선 코드에서 작업하는 기존 엔지니어가 안전한 변경을 하는 데 필요한 것을 가지고 있는가, 아니면 그 지식이 줄어드는 수의 재직 인원의 머릿속에만 사는가.

여기서의 측정 과제는 진정으로 어려운데, 이 책의 대부분의 다른 메트릭보다 더 어려운데, 문서화 품질과 유용성이 커버리지 백분율이나 복잡도 점수보다 본질적으로 더 주관적이기 때문이다. 이 주제의 접근법은 존재가 아니라 유용성에 대한 대리 지표를 측정하는 것이다: 문서가 실제로 얼마나 자주 접근되는지, 문서화된 답이 존재함에도 같은 질문이 얼마나 자주 반복적으로 제기되는지, 그리고 시스템에 낯선 누군가가 생산적이 되는 데 얼마나 걸리는지. 이 대리 지표 중 어느 것도 그 자체로 완벽하지 않지만, 함께는 코드베이스가 포함하는 위키 페이지나 README 파일의 수를 세는 것보다 훨씬 더 정직한 그림을 준다.

대규모 팀에게 이 주제의 관심사는 위기가 그 문제를 강제할 때까지 과소평가하기 쉬운 방식으로 조직적 재직 기간 및 이직과 복합된다: 같은 두 엔지니어가 수년 동안 유지한 시스템은 거의 아무런 서면 문서 없이도 완벽하게 잘 작동할 수 있다, 그 두 엔지니어가 같은 해에 떠날 때까지는, 그 시점에 조직은 그 지식이 실제로 지속 가능한 어떤 곳에도 결코 포착된 적이 없었다는 것을 발견한다. 전형적으로 스타트업보다 더 긴 시스템 수명과 덜 확실한 직원 연속성을 가진 엔터프라이즈와 정부 조직은 대부분보다 더 날카롭게 이 위험을 지닌다.

핵심 원칙

문서의 존재는 문서의 유용성과 같지 않다. 단지 존재하는지가 아니라 실제로 도움이 되는지 측정하라.
문서화된 답이 있음에도 반복되는 질문은 문서화 노력 문제가 아니라 발견 가능성 문제를 드러낸다. 더 많은 콘텐츠가 항상 해결책인 것은 아니다.
생산적인 기여까지의 온보딩 시간은 전반적인 지식 건강에 대한 강력하고 실용적인 대리 지표다, 주제 3.5의 협업 메트릭에 직접 연결된다.
사람들의 머릿속에만 사는 지식은 그것이 현재 아무리 잘 작동하더라도 안정적이고 지속 가능한 상태가 아니라 지속성 위험이다.
문서화는 부패한다. 1년 전에 정확했던 페이지는 이제 적극적으로 오도하고 있을 수 있으며, 그 오래됨 자체가 추적될 필요가 있다.

권장 사항

단지 존재뿐 아니라 문서 접근과 오래됨을 추적하라

당신의 문서화 플랫폼이 그것을 지원하는 곳에서는, 페이지가 실제로 얼마나 자주 조회되는지, 그리고 별도로, 그것이 서술하는 근본적인 시스템이 얼마나 자주 변했는지에 상대적으로 페이지가 마지막으로 업데이트된 지 얼마나 되었는지 추적하라(주제 4.3의 처닝 데이터를 교차 참조하는 것이 여기서 직접 유용하다). 페이지가 마지막으로 편집된 이후 상당히 변경된 시스템을 서술하는 페이지는 단지 도움이 되지 않는 것이 아니라 적극적으로 오도하고 있을 강력한 후보이며, 이 오래됨 신호는 문서가 조금이라도 존재하는지 추적하는 것만큼이나 많은 관심을 받을 자격이 있다.

발견 가능성 신호로서 반복되는 질문을 경계하라

문서화된 답이 기술적으로 어딘가에 존재함에도 같은 질문이 팀 채팅 채널이나 온보딩 중에 반복적으로 제기된다면, 그 패턴은 더 많은 글쓰기가 고칠 문서화 노력 문제가 아니라 발견 가능성 문제, 즉 답이 사람들이 자연스럽게 찾는 곳에 없다는 것을 드러낸다. 반복되는 질문을 명시적으로 추적하고, 그것을 사용해 더 많은 콘텐츠를 작성하는 것보다 기존 콘텐츠를 재구성하거나 더 잘 드러내는 것의 우선순위를 정하라.

첫 의미 있고 독립적인 기여까지의 온보딩 시간을 측정하라

주제 3.5에서 협업 신호로 도입된 이 메트릭은 코드 측면에서 동등하게 문서화와 지식 건강 신호다. 일관되게 짧고 예측 가능한 온보딩 시간은 진정으로 접근 가능하고 정확한 지식을 시사한다. 길고 매우 가변적인 시간, 특히 새로운 팀원을 온보딩하는 특정 사람이 누구인지에 크게 의존하는 시간은 지속 가능하고 서면화된 형태가 아니라 위험하게 개인의 기억에 집중된 지식을 시사한다.

문서화되지 않은 중요 지식 영역을 명시적으로 식별하고 우선순위를 정하라

당신의 지식 집중 데이터(주제 3.5의 버스 팩터 분석)를 문서화 커버리지와 교차 참조하라: 버스 팩터가 1이고 의미 있는 문서화가 전혀 없는 시스템은 동일하게 낮은 버스 팩터를 가진 잘 문서화된 시스템보다 우선순위 관심을 받을 자격이 있는 심각하고 복합되는 위험인데, 문서화는 적어도 전용 후임자가 훈련되는 동안 부분적인 완화를 제공하기 때문이다.

문서화 부채를 당신의 기술 부채 백로그 안의 한 범주로 취급하라

문서화 간극을 별도로 비공식적으로 추적하는 대신, 특히 중요하고 버스 팩터가 낮은 시스템에 대해, 주제 4.5에 서술된 것과 동일한 눈에 보이고 정량화된 백로그에 상당한 문서화 간극을 접어 넣어, 문서화 작업이 코드 중심 부채 개선에 비해 영원히 낮은 지위의 작업으로 미뤄지는 대신 우선순위가 매겨진 역량을 두고 공정하게 경쟁하게 하라.

트레이드오프: 장단점

접근법	장점	단점
문서화 측정 없음	낮은 오버헤드	지식 위험이 위기가 발견을 강제할 때까지 보이지 않게 남음
문서화 존재 세기 (페이지 수, README 유무)	단순하고, 보고하기 쉬움	유용성, 정확성, 혹은 발견 가능성에 대해 아무것도 말해 주지 않음
접근과 오래됨 추적하기	실제 유용성과 부패를 드러냄	문서화 플랫폼 분석과 지속적인 리뷰 규율이 필요함
대리 지표로서의 온보딩 시간	실용적이고, 구체적이며, 실제 비즈니스 영향에 직접 연결됨	간접적임; 문서화 외의 다른 요인도 온보딩 속도에 영향을 미침

핵심 긴장은 측정 가능성 대 의미다. 문서화의 존재는 사소하게 세기 쉽고 거의 아무런 유용한 것도 말해 주지 않는다. 진정한 유용성, 즉 누군가 필요할 때 문서화된 지식을 실제로 찾아서 의존할 수 있는지는 실제로 중요하지만 직접 측정하기 더 어렵다. 이 주제가 권장하는 대리 지표, 즉 접근 패턴, 처닝에 상대적인 오래됨, 반복되는 질문, 온보딩 시간을 조합하여 사용하고, 어느 하나도 완벽하지 않지만 그것들의 수렴이 존재 개수 홀로보다 훨씬 더 의미 있다는 것을 받아들임으로써 이 긴장을 해결하라.

팀과 논의할 질문

우리의 가장 중요하고 버스 팩터가 가장 낮은 시스템에 대해, 의미 있고 정확한 문서화가 실제로 존재하는가, 아니면 떠나는 전문가가 실제 지식의 대부분을 가져갈까? 이것은 이 주제의 핵심 관심사의 가장 날카롭고 가장 구체적인 버전이다. 먼저 당신의 단 하나의 가장 위험한 시스템에 대해 정직하게 답하라.
문서화된 답이 어딘가에 존재함에도 우리 팀 채팅에서 반복적으로 제기되는 질문은 무엇인가? 즉시 하나의 이름을 댈 수 있다면, 그것은 직접 고칠 가치가 있는 발견 가능성 문제이며, 아마도 더 많이 쓰는 것보다 기존 콘텐츠를 재구성하거나 더 잘 드러냄으로써다.
우리의 가장 최근 신입 팀원이 첫 의미 있고 독립적인 기여를 하는 데 얼마나 걸렸으며, 그것은 그 전의 팀원과 어떻게 비교되는가? 개인 간의 크고 설명되지 않는 차이는 흔히 지속 가능하고 접근 가능한 문서화가 아니라 누가 우연히 누군가를 온보딩하는지에 크게 의존하는 지식을 가리킨다.
문서의 한 조각이 그것이 작성된 이후 근본적인 시스템이 얼마나 변했는지에 상대적으로 여전히 정확한지 우리는 마지막으로 언제 확인했는가? 정직한 답이 “우리는 이것을 체계적으로 확인하지 않는다”라면, 그 오래됨 위험은 현재 누구든 가정하는 것보다 더 클 가능성이 있다.
우리의 기술 부채 백로그(주제 4.5)는 문서화 간극을 포함하는가, 아니면 문서화 작업이 코드 수정에 비해 영원히 더 낮은 지위의 작업으로 미뤄지는가? 당신의 실제 백로그를 확인하고 문서화 부채가 눈에 보이고 우선순위가 매겨진 역량을 두고 경쟁하는지, 아니면 사실상 보이지 않는지 확인하라.
우리의 가장 중요하고 가장 적게 문서화된 시스템을 이해하는 한두 사람이 같은 해에 떠난다면 우리에게 무슨 비용이 들까? 이 구체적이고 불편한 질문은 그 위험을 추상적이거나 가능성이 낮은 것으로 취급하는 대신 정직하게 답할 가치가 있다.

분야별 관점

스타트업. 지식이 끊임없고 직접적인 대화를 통해 퍼지는 소규모 팀에서는 공식적인 문서화 메트릭이 보통 불필요하다. 지켜봐야 할 위험은 이제 특별히 문서화에 적용된, 주제 3.5가 경고하는 것과 동일한 버스 팩터 집중이다: 팀이 모두가 매일 대화하는 규모를 넘어 성장함에 따라 비공식적으로는 잘 작동했던 문서화되지 않은 지식이 실제 부채가 된다.

중소기업. 모든 것에 걸쳐 포괄적인 문서화를 시도하는 대신, 비공식적일지라도 당신의 단 하나의 가장 중요하고 가장 중복되지 않는 시스템을 먼저 문서화하는 것을 우선순위로 삼아라. 당신의 가장 위험한 단일 실패 지점을 다루는 짧고 정확한 문서는 모든 곳에서의 넓지만 얕은 커버리지보다 더 많은 실제 가치를 전달한다.

엔터프라이즈. 문서화 오래됨과 발견 가능성 둘 다 여기서 나쁘게 확장되는데, 대규모 조직은 누구든 그것을 최신이거나 일관되게 조직된 상태로 유지할 수 있는 것보다 더 빠르게 많은 팀과 플랫폼에 걸쳐 문서화를 축적하기 때문이다. 규모에서 접근과 오래됨을 추적하기 위해 문서화 플랫폼 분석에 투자하고, 조직 전체의 부채 백로그에서 문서화 부채를 일급 범주로 취급하라.

정부. 공공 부문 조직에서 흔한 긴 직원 재직 기간은 겉보기의 안정성 뒤에 심각한 문서화되지 않은 지식 위험을 가릴 수 있는데, 같은 사람이 15년 동안 유지한 시스템은 그 사람이 은퇴하기 직전까지 완벽하게 잘 작동할 수 있기 때문이다. 단지 엔지니어링상의 바람직함이 아니라 인력 및 후임자 계획에 직접 연결된 운영 연속성 관심사로 문서화 건강을 명시적으로 취급하라.

사례

엔터프라이즈. 한 금융 서비스 회사는 무관한 재조직 중에 그 핵심 위험 계산 엔진이 몇 개의 낡은 코드 코멘트 외에는 의미 있는 문서화가 전혀 없으며, 그것을 가장 잘 이해하는 두 엔지니어가 동시에 새로운 이니셔티브로 재배치되고 있다는 것을 발견했다. 상당한 시간 압박 아래 수행된 긴급 문서화 노력은 재배치가 효력을 발휘하기 전에 중요한 지식을 추출하고 기록했지만, 그 절차는 만약 문서화 건강이 선제적으로 추적되고 우선순위가 매겨졌더라면 더 점진적으로 그리고 더 저렴하게 퍼질 수 있었을 몇 주간의 전담 고참 엔지니어 시간이 걸렸다.

정부. 한 주 정부의 수십 년 된 사례 관리 시스템은 수년에 걸쳐 상당한 문서화를 축적했지만, 발견 가능성 감사는 신입 팀원이 지속적으로 관련 기존 문서화를 찾을 수 없었고 팀 채널에서 같은 소수의 질문을 반복적으로 물었다는 것을 발견했으며, 그 질문들은 사실 그 기관의 방대하고 잘 조직되지 않은 문서화 플랫폼 어딘가에 이미 답이 있었다. 더 많은 콘텐츠를 작성하는 대신, 그 기관은 기존 문서화의 검색 및 탐색 구조를 재구성하고 개선하는 데 투자했고, 후속 설문은 반복되는 질문의 측정 가능한 감소와 신입 직원에 대해 의미 있게 더 빠르다고 보고된 온보딩 경험을 보여 주었으며, 단 한 페이지의 새로운 콘텐츠도 추가하지 않고 그렇게 했다.

비즈니스 사례: 동기, ROI, TCO

문서화 건강을 의도적으로 측정하고 관리하는 것의 수익은 예방된 위기 비용이다: 위의 금융 서비스 사례는 능동적이고 점진적인 지식 포착과 계획되지 않은 직원 이동에 의해 강제된 비싸고 압축된 긴급 노력 사이의 차이를 보여 준다. 문서화되지 않은 중요한 지식은 그것이 한꺼번에 매우 비싸지는 순간까지는 눈에 보이게 아무런 비용도 들지 않는 상시적인 부담이다.

총 소유 비용은 대체로 이 주제가 권장하는 대리 지표, 즉 접근 패턴, 오래됨, 반복되는 질문, 온보딩 시간을 추적하는 규율과, 문서화 간극을 코드 중심 작업보다 영원히 더 낮은 지위로 취급하는 대신 우선순위가 매겨진 백로그에 접어 넣으려는 의지다. 그 규율은 금융 서비스 사례가 대안으로 보여 주는 위기 모드의 지식 추출보다 훨씬 더 적은 비용이 든다.

안티패턴과 함정

유용성이 아니라 문서화 존재를 세기: 지식이 필요할 때 실제로 접근 가능한지에 대해 거의 아무것도 말해 주지 않는다.
먼저 발견 가능성을 확인하지 않고 반복되는 질문에 대응해 더 많은 콘텐츠 작성하기: 흔히 완전히 잘못된 문제를 다룬다.
시스템이 얼마나 변했는지에 상대적으로 문서화 오래됨을 결코 확인하지 않기: 적극적으로 오도하는, 구식 콘텐츠의 위험을 무릅쓴다.
문서화 부채를 코드 부채보다 영원히 더 낮은 지위로 취급하기: 그것을 만성적으로 우선순위가 낮고 백로그에서 보이지 않게 남긴다.
겉보기의 안정성, 즉 수년 동안 변하지 않은 시스템을 낮은 위험으로 착각하기: 단지 아직 그 유일한 전문가를 필요로 하지 않은 시스템 뒤에 심각하고 문서화되지 않은 버스 팩터 문제를 가릴 수 있다.
긴급한 직원 전환 중에만 중요한 문서화되지 않은 지식을 발견하기: 이 주제가 예방하도록 만들어진 비싸고 피할 수 있는 실패 양상.

성숙도 모델

1단계, 시작: 문서화 건강이 측정되지 않는다. 지식 집중과 오래됨 위험은 오직 위기를 통해서만 발견된다.
2단계, 개발: 일부 문서화가 존재하지만, 접근, 오래됨, 혹은 발견 가능성에 대한 체계적인 추적이 없다.
3단계, 표준화: 중요한 시스템에 대해 접근과 오래됨이 추적되며, 조직 전체에서 지식 건강의 대리 지표로 온보딩 시간이 측정된다.
4단계, 관리: 문서화 간극이 우선순위가 매겨진 기술 부채 백로그에 접어 넣어지며, 가장 심각한 결합된 위험을 식별하기 위해 버스 팩터 위험과 교차 참조된다.
5단계, 조율: 조직은 인력 전환이 그 문제를 강제하기 전에 문서화되지 않은 중요 지식 위험을 선제적으로 식별하고 다루며, 문서화 투자로 거슬러 올라가는 구체적이고 측정 가능한 온보딩이나 인시던트 대응 개선을 제시할 수 있다.

논의를 위한 아이디어

지금 낮은 버스 팩터와 열악한 문서화의 가장 심각한 단일 조합은 무엇인가?
문서화된 답이 존재함에도 반복적으로 제기되는 질문은 무엇인가?
중요한 문서의 한 조각이 오래되고 오도하게 되었다면 우리는 어떻게 알 수 있을까?
우리의 기술 부채 백로그는 문서화 간극을 포함하는가, 아니면 그것들은 보이지 않는가?
가장 문서화가 부족한 시스템의 유일한 전문가가 올해 떠난다면 우리에게 어떤 비용이 들까?

핵심 요약

존재가 아니라 유용성을 측정하라: 접근 패턴, 오래됨, 반복되는 질문 같은 대리 지표를 사용해 문서화가 실제로 도움이 되는지.
문서화된 답이 있음에도 반복되는 질문은 반드시 콘텐츠 노력 문제가 아니라 발견 가능성 문제를 드러낸다.
생산적인 기여까지의 온보딩 시간은 전반적인 지식 건강에 대한 강력하고 실용적인 대리 지표다.
문서화되지 않은 중요 지식은 복합되는 위험이며, 특히 낮은 버스 팩터(주제 3.5)와 결합될 때 그렇다. 그것은 한꺼번에 큰 비용이 들기 전까지는 눈에 보이게 아무런 비용도 들지 않는다.
문서화 간극을 당신의 기술 부채 백로그(주제 4.5)에 접어 넣어 그것들이 우선순위가 매겨진 역량을 두고 공정하게 경쟁하게 하라.

참고 문헌 및 추가 자료

Bhatti, Jared, Zachariah Goldberg, Ted Kubaska, and Sarah Moir. Docs for Developers: An Engineer’s Field Guide to Technical Writing. Apress, 2021.
Ousterhout, John. A Philosophy of Software Design. Yaknyam Press, 2018.
Skelton, Matthew, and Manuel Pais. Team Topologies: Organizing Business and Technology Teams for Fast Flow. IT Revolution Press, 2019.
Forsgren, Nicole, Jez Humble, and Gene Kim. Accelerate: The Science of Lean Software and DevOps. IT Revolution Press, 2018.