2.7 문서화

개요와 동기

문서화는 사람들이 코드만으로 이해를 짜 맞추지 않고도 소프트웨어를 사용하고, 운영하고, 바꿀 수 있게 하는 서면 지식입니다. 여러 장르가 있습니다. 시작하는 방법, 과제를 수행하는 방법, 시스템이 어떻게 구성되어 있는지, 인시던트에 어떻게 대응하는지, API가 무엇을 받아들이고 반환하는지입니다. 각각이 서로 다른 필요를 가진 서로 다른 독자를 섬깁니다. 좋은 문서화는 선택 사항이 아닙니다. 큰 조직에 걸쳐 확장되는 지식과 몇 사람의 머릿속에만 사는 지식의 차이입니다.

큰 팀에서 문서화는 핵심 인력 위험(핵심 지식이 한두 사람에게만 있는 위험)에 대한 최선의 방어이자 신입을 온보딩하는 가장 빠른 방법입니다. 수백 명의 엔지니어가 자신이 만들지 않은 시스템에 의존하고, 사람들이 끊임없이 합류하고, 옮기고, 떠날 때, 조직은 지식이 글로 쓰이고 찾기 쉬울 때만 기능할 수 있습니다. 문서화되지 않은 시스템은 취약해집니다. 작성자만 안전하게 바꿀 수 있고, 그 작성자가 떠나면 조직은 자기 소프트웨어를 유지할 능력을 잃습니다. 이것은 규모에서 가장 흔하고 비싼 실패 중 하나입니다.

기업과 정부 맥락은 이해관계를 더 높입니다. 시스템은 오래 살므로, 문서화는 원래 팀이 사라진 지 여러 해, 심지어 수십 년 뒤의 유지보수자를 섬겨야 합니다. 규제와 감사 체계는 통제의 증거로 특정 문서를 의무화하는 경우가 많습니다. 아키텍처 기록, 런북(단계별 운영 및 인시던트 대응 절차), 결정 로그입니다. 벤더 사이를 넘겨받는 공공 부문 시스템은 계약 경계를 넘어 지식을 전달하는 일을 전적으로 문서화에 의존합니다. 그럼에도 문서화는 썩기 쉽기로 유명하므로, 진짜 과제는 소프트웨어가 바뀌는 동안 정확하게 유지하는 것입니다.

핵심 원칙

특정한 필요를 가진 특정한 독자를 위해 쓰십시오. 다른 유형의 문서화는 다른 목적에 봉사합니다.
문서화를 코드 가까이에 두고 코드처럼 다루십시오(docs-as-code).
완전함보다 정확함. 소량의 신뢰할 수 있는 문서화가 틀린 대량의 문서화보다 낫습니다.
생성할 수 있는 것은 생성하십시오. 도구가 진실의 원천에서 만들어 낼 수 있는 것을 손으로 유지하지 마십시오.
문서화의 부패와 적극적으로 싸우십시오. 낡은 문서는 오도하므로 없는 것보다 나쁩니다.
문서화를 찾을 수 있게 하십시오. 찾을 수 없는 지식은 사실상 없는 것입니다.
현재 상태만이 아니라 결정과 그 근거를 기록하십시오.

권장 사항

docs-as-code를 채택한다

문서화를 설명하는 코드와 나란히 버전 관리에 두고, 일반 텍스트 마크업으로 쓰고, 같은 풀 리퀘스트 프로세스로 리뷰하십시오. 그러면 버전이 관리되고, 리뷰 가능하고, 코드에 가까워서 둘을 함께 갱신할 수 있습니다. 자동화된 파이프라인으로 게시하여 최신 버전이 항상 이용 가능하게 하십시오. 문서를 코드로 다루면 코드를 신뢰할 수 있게 유지하는 같은 규율, 즉 리뷰, 이력, 자동화를 가져옵니다.

Diátaxis 프레임워크로 콘텐츠를 구조화한다

문서화를 네 가지 뚜렷한 유형으로 조직하십시오. 섞으면 어떤 독자도 잘 섬기지 못하기 때문입니다. 튜토리얼(학습 지향, 신입용), 하우투 가이드(과제 지향, 특정 목표용), 참조(정보 지향, 정확하고 완전함), 설명(이해 지향, 이유와 맥락)입니다. 이들을 분리해 두면 모든 것이 쓰고, 탐색하고, 유지하기 쉬워집니다. 각 페이지가 하나의 분명한 역할과 하나의 분명한 독자를 갖기 때문입니다.

필수 운영 문서를 유지한다

모든 저장소에 앞문으로서 분명한 README를 두십시오. 그것이 무엇인지, 어떻게 빌드하고 실행하는지, 다음에 어디로 갈지입니다. 전문가만이 아니라 온콜 담당자 누구나 행동할 수 있도록 운영 과제와 인시던트 대응을 위한 런북을 쓰십시오. 시스템의 구조와 핵심 구성 요소를 설명하는 아키텍처 문서화를 유지하십시오. 그리고 신규 엔지니어가 빠르게 생산적이 되게 하는 온보딩 문서를 제공하십시오. 이것들이 없을 때 가장 아쉬운 문서입니다.

API 문서와 변경 로그를 진실의 원천에서 생성한다

API 참조 문서를 기계가 읽을 수 있는 계약이나 코드 주석에서 생성해 실제 인터페이스에서 벗어나지 않게 하십시오. 소비자가 버전 사이에 무엇이 바뀌었는지 볼 수 있도록 이상적으로는 구조화된 커밋이나 릴리스 노트에서 생성되는 변경 로그를 유지하십시오. 이를 자동화하면 가장 부패하기 쉬운 손으로 유지되는 문서가 여러분의 접시에서 사라지고 신뢰할 수 있게 유지됩니다.

아키텍처 결정을 기록한다

중대한 아키텍처 및 설계 결정을 맥락, 결정, 결과를 밝히는 가볍고 날짜가 있는 기록으로 포착하십시오. 이런 결정 기록은 그렇지 않으면 사라질 근거를 보존해, 미래의 유지보수자가 시스템이 왜 그런 모양인지 보고 의문을 품거나 옛 실수를 반복하지 않게 합니다. 기업과 정부 시스템의 긴 수명에 걸쳐 특히 본전을 뽑습니다.

문서화 부패와 의도적으로 싸운다

낡은 문서화를 결함으로 다루십시오. 동작을 바꾸는 같은 변경의 일부로 문서를 갱신하고 이를 리뷰의 기대로 만드십시오. 모든 중요한 문서에 책임자가 있도록 소유권을 배정하십시오. 가치 높은 문서화를 이따금 정확성에 대해 검토하고, 낡은 것은 쳐내고, 더는 신뢰하지 않는 것은 제거하거나 분명히 표시하십시오. 가장 덜 부패하는 문서화는 살아 있는 문서화, 즉 시스템 자체에 대해 생성되거나 테스트되는 것입니다.

지식 관리와 찾을 수 있음에 투자한다

좋은 검색, 분명한 탐색, 알려진 홈을 통해 문서화를 찾을 수 있게 만들어 사람들이 누구에게 묻지 않고도 필요한 것을 찾을 수 있게 하십시오. 너무 많은 단절된 위키와 도구로 파편화되지 않게 하십시오. 그리고 채팅 스레드와 사람들의 머릿속에 사는 비공식적 이해인 암묵지를 사라지기 전에 오래 남고 찾을 수 있는 형태로 포착하십시오.

장단점

접근 방식	장점	단점
Docs-as-code	버전 관리됨, 리뷰 가능, 코드에 가까움. 낮은 부패	엔지니어의 규율이 필요. 비기술 작성자에게 덜 친화적
위키 / 지식 베이스	편집하기 쉬움. 모두가 접근 가능	코드에서 어긋남. 파편화됨. 조용히 부패
생성된 문서 (API, 변경 로그)	항상 정확. 낮은 유지보수	원천이 표현하는 것으로 제한됨. 도구가 필요
손으로 쓴 설명	기계가 만들 수 없는 풍부한 맥락과 근거	노동 집약적. 낡기 쉬움
Diátaxis 구조	페이지마다 분명한 목적. 탐색과 유지가 쉬움	선행 구조화 노력. 작성자의 규율 필요

핵심 트레이드오프는 노력 대 정확성과 내구성입니다. 가장 쓰기 싼 문서화인 빠른 위키 페이지는 부패와 파편화에도 가장 취약합니다. 가장 오래가는 문서화, 즉 원천에서 생성되거나 코드로 리뷰되는 것은 선행 규율이 더 들지만 신뢰할 수 있게 유지됩니다. 좋은 경험칙은 이렇습니다. 생성할 수 있는 것은 생성하고, 나머지는 코드 가까이에 두고 코드처럼 리뷰하며, 노동 집약적인 손으로 쓴 설명은 사람만이 줄 수 있는 근거에 남겨 두십시오.

팀과 논의할 질문

문서가 독자의 필요에 따라 분리되어 있습니까, 아니면 튜토리얼, 참조, 설명이 한 페이지에 뒤섞여 있습니까? 이 장은 튜토리얼, 하우투 가이드, 참조, 설명으로의 Diátaxis 분리를 권하고, 유형을 섞는 것을 어떤 독자도 잘 섬기지 못하는 안티패턴으로 꼽습니다. 규모에서 시스템을 배우는 신입과 정확한 사실을 찾는 온콜 엔지니어는 서로 다른 페이지가 필요하며, 하나의 혼합 페이지는 둘 다를 늦춥니다. 신호를 가져오십시오. 가장 많이 방문되는 문서를 골라 각각이 하나의 분명한 역할과 하나의 분명한 독자를 갖는지 확인하십시오. 최악의 사례를 뚜렷한 유형으로 재구성해, 모든 페이지가 쓰고, 탐색하고, 최신으로 유지하기 더 쉽게 하십시오. 그 구조가 조직이 커져도 문서화를 유지보수 가능하게 합니다.
중대한 아키텍처 결정을 현재 상태만이 아니라 그 근거와 함께 포착합니까? 이 장은 맥락, 결정, 결과를 밝히는 가볍고 날짜가 있는 결정 기록을 권하며, 기업과 정부 시스템의 긴 수명에 걸쳐 가장 본전을 뽑는다고 지적합니다. 그것이 없으면 몇 년 뒤의 유지보수자는 시스템이 왜 그런 모양인지 볼 수 없어서, 건전한 선택에 의문을 품거나 옛 실수를 반복합니다. 이유가 이제 채팅 스레드나 누군가의 기억에만 있는 최근의 어려운 결정을 구체적 신호로 가져오십시오. 짧은 결정 기록 형식을 채택하고 중대한 설계 변경의 일부로 하나를 쓰게 하십시오. 근거는 사람만이 줄 수 있고 적히지 않으면 가장 빨리 부패하는 바로 그 지식입니다.
온콜 엔지니어 누구나 시스템을 만든 사람을 호출하지 않고 런북만으로 인시던트에 대응할 수 있습니까? 이 장은 런북을 전문가만이 아니라 온콜 누구나 행동할 수 있도록 하는 필수 운영 문서로 이름 붙이고, 런북이 계약 경계를 넘어 지식을 전달했기 때문에 시스템을 물려받을 수 있었던 정부 팀을 기술합니다. 핵심 인력 위험이 이것이 막는 실패입니다. 유일한 전문가에게 연락이 닿지 않거나 떠났을 때, 문서화되지 않은 복구 절차는 일상적인 인시던트를 장애로 바꿉니다. 증거를 가져오십시오. 최근 인시던트를 골라 런북만으로 해결할 수 있었는지 확인하십시오. 사람들이 두려워하는 절차에 대한 런북을 쓰고 테스트하고, 스스로 설 수 없는 런북은 결함으로 다루십시오. 새벽 2시의 복구와 새벽 2시의 에스컬레이션의 차이입니다.
API 참조와 변경 로그 중 어느 것이 진실의 원천에서 생성되고, 어느 것이 여전히 손으로 유지되며 조용히 표류하고 있습니까? 이 장은 참조 문서를 기계가 읽을 수 있는 계약이나 코드 주석에서 생성하여 실제 인터페이스에서 벗어날 수 없게 하라고 하며, 생성 가능한 콘텐츠를 손으로 유지하는 것을 안티패턴으로 꼽습니다. 큰 팀에서 실제 인터페이스보다 뒤처진 손으로 쓴 API 문서는 없는 것보다 나쁩니다. 그것을 신뢰하는 모든 소비자가 깨진 통합을 쓰고, 실패는 그것을 일으킨 낡은 페이지에서 멀리 떨어진 곳에 나타납니다. 구체적 신호를 가져오십시오. 가장 많이 쓰이는 인터페이스 몇 개를 표본으로 골라 공개된 참조를 실제 계약과 비교하여 각각이 얼마나 표류했는지 보십시오. 표류를 발견하면 참조를 빌드에 연결해 모든 변경마다 재생성되게 하고, 손으로 유지하던 사본은 폐기하십시오. 인터페이스가 팀, 벤더, 보이지 않는 계약 경계를 가로질러 소비되는 기업과 정부 환경에서, 권위 있는 생성된 참조는 통합자가 허구에 맞춰 만들지 않게 하는 유일한 것인 경우가 많습니다.
가치 높은 문서마다 누가 소유하며, 오늘 하나가 낡았다면 어떻게 알아챌 수 있습니까? 이 장은 낡은 문서화를 결함으로 다루며, 소유자 없는 문서는 갱신이 누구의 일도 아니어서 부패하고, 현재인 것처럼 제시되는 낡은 문서가 모든 문서화에 대한 신뢰를 파괴한다고 경고합니다. 규모에서 위험은 틀린 페이지 하나가 아니라 신뢰의 느린 침식입니다. 독자가 낡은 지침에 데이고 나면 전체 코퍼스를 신뢰하지 않고 사람들을 방해하는 데로 돌아갑니다. 가장 핵심적인 문서의 소유 지도와, 부패가 어떻게 탐지되는지에 대한 정직한 답을 가져오십시오. 검토 주기인지, 생성인지, 시스템에 대한 테스트인지, 순전한 운인지입니다. 중요한 모든 문서에 이름 있는 소유자를 배정하고, 낡음이 당혹한 독자를 통해서가 아니라 기계적으로 드러나도록 생성되거나 테스트되는 살아 있는 문서화를 선호하십시오. 원래 팀보다 오래 사는 기업과 정부 시스템에서 소유자 없는 문서화는 감사자나 물려받는 벤더가 결국 청구할 부채입니다.
문서화는 얼마나 찾을 수 있으며, 얼마나 많은 핵심 지식이 여전히 채팅 스레드와 사람들의 머릿속에만 있습니까? 이 장은 찾을 수 없는 지식이 사실상 없는 것이라고 말하며, 너무 많은 단절된 위키와 도구로 문서를 파편화하는 것을 경고하고, 암묵지를 사라지기 전에 오래 남고 찾을 수 있는 형태로 포착하라고 촉구합니다. 큰 조직에서는 같은 사실이 이미 어디에 적혔는지 아무도 찾을 수 없어서 백 번 재발견되고, 다시 질문되고, 다시 답해지며, 모든 퇴사가 대체할 수 없는 맥락을 문밖으로 가져갑니다. 증거를 가져오십시오. 유지하는 별개의 문서화 홈이 몇 개인지 세고, 검색만으로 중요한 사실 세 가지를 찾아 보고, 진짜 답이 어디서 누군가의 기억이나 묻힌 메시지에 있었는지 기록하십시오. 진짜 검색과 분명한 탐색이 있는 알려진 홈으로 통합하고, 암묵지를 포착하는 일을 영웅적인 구조가 아니라 일의 일상적인 부분으로 만드십시오. 시스템이 계약으로 벤더와 팀 사이를 넘겨지는 공공 부문과 아웃소싱이 많은 맥락에서, 찾을 수 있는 서면 지식은 인수인계를 견디는 유일한 것입니다.

분야별 관점

스타트업. 엔지니어 몇 명과 여유 없는 런웨이라면, 새벽 2시의 장애나 신규 입사자가 실제로 필요로 할 것만 문서화하십시오. 서비스별 진짜 README, 모두가 두려워하는 배포-복구 절차를 위한 테스트된 런북 하나, 그렇지 않으면 잊을 결정에 대한 날짜 있는 몇 개의 메모입니다. API 문서는 계약에서 생성하여 손으로 유지하지 마십시오. 문서화 플랫폼을 만들려는 것에 저항하십시오. 진짜 고통을 느끼기 전까지는 코드 옆의 버전 관리되는 마크업 폴더면 충분합니다.

소기업. 기술 문서 작성자도 빠듯한 예산도 있으니, 인력이 있는 프로그램 대신 도구가 이미 생성하는 문서화와 가벼운 docs-as-code에 의지하십시오. 선택을 구매 대 개발로 설명하십시오. 손으로 가꿔야 하는 위키보다 스스로 최신 참조와 검색 가능한 지식 베이스를 만드는 플랫폼을 선호하십시오. 부재가 사업을 멈출 두세 개의 문서에 희소한 노력을 쓰고, 틀리거나 빠진 페이지가 소유권을 고치는 계기가 되게 하십시오.

대기업. 많은 팀에 걸쳐 문제는 일관성과 찾을 수 있음입니다. 공유 docs-as-code 파이프라인, Diátaxis 같은 공통 구조, 생성된 API 참조와 변경 로그, 지식이 수십 개 위키에 파편화되지 않도록 어디서나 같은 방식으로 적용되는 결정 기록입니다. 가치 높은 모든 문서에 소유권을 배정하고 존재만이 아니라 정확성을 측정하십시오. 아키텍처 기록, 런북, 결정 로그를 감사 증거로 다루고, 통제 검토가 허둥지둥이 아니라 문서화된 방어 가능한 흔적을 찾도록 그 생산 방식을 표준화하십시오.

정부. 조달 규칙과 공적 책임성이 문서화를 예의가 아닌 산출물로 만듭니다. 아키텍처 문서화, 런북, 결정 기록을 의무 산출물로 계약에 써넣고 정확성을 검토하여, 벤더 전환에서도 지식이 살아남고 시스템을 물려받는 누구든 운영할 수 있게 하십시오. 승인된 운영자 누구나 런북만으로 인시던트에 대응할 수 있도록 요구하고, 결정 로그를 선택이 왜 이루어졌는지의 투명한 공적 기록으로 유지하십시오. 여기서 얇은 문서화는 사적 불편이 아닙니다. 납세자가 재원을 대는 값비싼 역공학이 됩니다.

사례

스타트업. 다섯 명 규모의 스타트업은 서비스마다 진짜 README를, 모두가 두려워하는 배포-복구 절차 하나에 짧은 런북을 써서, 새벽 2시의 장애가 시스템을 아는 단 한 명의 창업자를 깨우는 데 달려 있지 않게 합니다. API 문서는 손으로 쓰지 않고 계약에서 생성하고, 데이터베이스와 인증 방식을 고른 이유를 설명하는 날짜 있는 메모 몇 개를 적어 둡니다. 가볍게 유지되지만, 여섯 번째와 일곱 번째 채용자가 모두를 방해하지 않고 문서로 온보딩한다는 뜻입니다.

대기업. 한 대형 소프트웨어 회사는 모든 문서화를 코드와 같은 저장소에 두고, 마크업으로 쓰고, 그것이 설명하는 변경 바로 옆에서 풀 리퀘스트로 리뷰합니다. API 참조는 서비스 계약에서 생성되므로 결코 표류하지 않습니다. 변경 로그는 구조화된 커밋에서 생성되고, 아키텍처 결정 기록은 주요 선택 뒤의 추론을 보존합니다. 게시된 문서 사이트는 모든 병합마다 자동으로 빌드됩니다. 온보딩 가이드와 런북이 최신이고 찾을 수 있어서 신규 엔지니어가 빠르게 생산적이 되고, 온콜 엔지니어는 원래 작성자를 호출하는 대신 런북에 의지합니다.

정부. 한 국가 기관이 떠나는 계약자로부터 시스템을 물려받으며, 계약 경계를 넘어 지식을 전달하는 일을 전적으로 문서화에 의존합니다. 이전 벤더가 아키텍처 문서화, 런북, 결정 기록을 의무 산출물로 유지했기 때문에, 새 팀은 원래 작성자 없이 시스템을 운영하고 수정할 수 있습니다. 문서화가 얇았던 곳에서는 기관이 값비싼 역공학에 직면합니다. 그 경험이 새 정책을 이끕니다. 문서화는 계약상의 산출물이며, 사후 생각으로 두지 않고 정확성을 검토하며, 런북은 승인된 운영자 누구나 인시던트에 대응할 수 있게 해야 합니다.

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

문서화는 더 짧은 온보딩 시간, 더 적은 핵심 인력 위험, 더 빠른 인시던트 대응, 시스템 수명에 걸친 더 낮은 변경 비용으로 보답합니다. 신규 엔지니어가 몇 주가 아니라 며칠 만에 생산적이 되고, 온콜 인력이 에스컬레이션하는 대신 런북으로 인시던트를 해결하고, 유지보수자가 시스템이 만들어진 지 여러 해 뒤에도 자신 있게 바꾸는 것. 이는 큰 조직과 긴 시스템 수명에 걸쳐 누적되는 크고 반복되는 절감입니다.

문서화에는 무엇이 듭니까? 작성과 유지보수의 노력입니다. 문서화하지 않는 데는 무엇이 듭니까? 끊임없이 치릅니다. 느린 온보딩, 반복되는 질문, 핵심 인력 병목, 더 느린 인시던트 복구, 그리고 극단적으로 아무도 안전하게 바꿀 수 없는 시스템이 되어 값비싼 재작성이나 역공학을 강제합니다. 벤더 전환과 감사 시나리오에서 빠진 문서화는 직접적인 계약 및 컴플라이언스 비용을 질 수 있습니다. 리더십을 설득하려면 온보딩 시간, 인시던트 대응 시간, 얼마나 많은 핵심 지식이 개인의 머릿속에 있는지에 숫자를 매기십시오. 그다음 docs-as-code와 생성을 그에 걸맞은 유지보수 부담 없이 오래가는 문서화를 얻는 방법으로 설명하십시오. 그리고 부정확한 문서화는 부채이므로 투자에는 그것을 최신으로 유지하는 것이 포함되어야 함을 강조하십시오.

안티패턴과 함정

현재인 것처럼 제시되는 낡은 문서화: 독자를 오도하고 모든 문서화에 대한 신뢰를 파괴합니다.
한 번 쓰는 위키: 만들어지고 한 번도 갱신되지 않아 현실에서 조용히 표류하는 페이지.
문서화 파편화: 지식이 많은 도구와 위키에 흩어져 아무것도 찾을 수 없는 것.
문서화 유형 섞기: 튜토리얼, 참조, 설명이 한 페이지에 뒤섞여 어떤 독자도 잘 섬기지 못하는 것.
생성 가능한 콘텐츠를 손으로 유지: 필연적으로 실제 인터페이스에서 벗어나는 수동 작성 API 문서.
부족 지식: 사람들의 머릿속과 채팅 기록에만 있다가 그들이 떠나면 사라지는 핵심 이해.
사후 생각으로서의 문서화: 변경과 나란히가 아니라, 있다 해도 마지막에 쓰이는 것.
소유자 없음: 책임자가 없는 문서는 갱신이 누구의 일도 아니어서 부패합니다.

성숙도 모델

1단계, 시작. 문서화가 드물고, 흩어져 있고, 낡았으며, 지식은 사람들의 머릿속에 있습니다. 존재하는 것은 한 번 쓰이고 다시 손대지 않아서, 장애나 퇴사는 시스템을 역공학하는 것을 뜻합니다.
2단계, 발전. README와 몇 개의 런북 같은 핵심 문서가 있지만 일관되지 않게 유지되고 찾기 어렵습니다. 어떤 팀은 잘 문서화하고 다른 팀은 거의 하지 않으며, 저장소가 무엇을 담아야 하고 어디에 있어야 하는지에 대한 공유된 기대가 없습니다.
3단계, 표준화. Docs-as-code가 조직 전체의 규범입니다. Diátaxis 같은 공통 구조, 생성된 API 참조와 변경 로그, 결정 기록, 문서가 설명하는 코드와 함께 바뀐다는 리뷰의 기대입니다. 가치 높은 모든 문서에 이름 있는 소유자가 있고, 진짜 검색이 있는 알려진 하나의 홈이 있습니다.
4단계, 관리. 문서화가 단지 존재하는 것이 아니라 측정됩니다. 필수 문서의 커버리지, 코드 변경률 대비 문서 변경률, 온보딩 시간, 런북만으로의 인시던트 해결, 정의된 낡음 임계값 대비 신선도를 추적하고, 기준선에 대해 그 지표를 검토합니다. 부패는 생성, 시스템에 대한 테스트, 링크 및 정확성 검사로 기계적으로 포착되고, 낡은 페이지는 우연이 아닌 증거에 따라 표시되거나 쳐내집니다.
5단계, 오케스트레이션. 문서화가 지속적으로 개선되고 조직 전체에 통합됩니다. 살아 있고, 대체로 생성되거나 시스템에 대해 테스트되고, 소유되고, 찾을 수 있고, 적응적입니다. 지표가 투자할 곳에 되먹임되고, 암묵지 포착이 일의 일상적인 부분이며, 코퍼스는 시스템, 팀, 독자가 변함에 따라 적극적으로 재균형되고 쳐내집니다.

논의를 위한 아이디어

내일 사라진다면 조직에 가장 아플 문서화는 무엇이며, 현재 존재하고 최신으로 유지됩니까?
문서 갱신을 별도의 잡무가 아니라 코드를 바꾸는 자연스러운 부분으로 만들려면 어떻게 합니까?
손으로 쓴 문서화를 진실의 원천에 연결된 생성된 문서화로 대체할 수 있는 곳은 어디입니까?
문서화가 존재하는 것만이 아니라 정확하고 쓰이는지 어떻게 측정합니까?
AI 어시스턴트는 문서화를 쓰고, 유지하고, 검색하는 방식을 어떻게 바꿔야 하며, 그럴듯하지만 틀린 콘텐츠를 어디서 도입할 수 있습니까?
암묵지를 가진 사람들이 떠나기 전에 어떻게 포착합니까?

핵심 요점

문서화를 코드로 다루십시오. 버전 관리되고, 리뷰되고, 원천에 가깝고, 자동으로 게시됩니다.
튜토리얼, 하우투 가이드, 참조, 설명으로 독자의 필요에 따라 콘텐츠를 구조화하십시오.
가치 높은 필수 문서를 유지하십시오. README, 런북, 아키텍처 문서, 온보딩, 결정 기록입니다.
API 문서와 변경 로그를 진실의 원천에서 벗어나지 않도록 생성하십시오.
소유권, 리뷰 기대, 쳐내기로 부패와 싸우십시오. 부정확한 문서화는 없는 것보다 나쁩니다.

참고 문헌과 더 읽을거리

Daniele Procida, Diátaxis documentation framework
Andrew Etter, Modern Technical Writing
Anne Gentle, Docs Like Code
Google, Developer Documentation Style Guide and Season of Docs guidance (as reference exemplars)
Michael Nygard, Documenting Architecture Decisions (architecture decision records)
Andrew Hunt and David Thomas, The Pragmatic Programmer (on knowledge and documentation)
Keep a Changelog (as a reference convention)