기술 문서는 아주 구체적이고 예측 가능한 방식으로 실패합니다. 누군가 한가한 2주 동안 아주 많은 양을 써 놓고, 그러는 사이 시스템이 바뀌고, 아무도 갱신하지 않고, 1년이 지나면 그 문서는 확신에 찬 어조로 틀린 내용을 말하고 있습니다. 그 시점부터는 없느니만 못합니다. 문서를 믿은 사람이 이미 성립하지 않는 정보에 근거해 움직이기 때문입니다.

흔한 대응은 더 많이 쓰자는 압박이고, 그것은 같은 실패를 더 빨리 불러올 뿐입니다. 쓸모 있는 대응은 더 적게 쓰고 무엇을 쓸지 고르는 것입니다. 병목은 쓰는 노력이 아니라 유지하는 노력이기 때문입니다.

어떤 문서가 존재할 가치가 있는지 가리는, 유일하게 오래가는 시험: 그 문서가 틀려졌을 때 누군가 알아차리는가? 배포 가이드는 실제로 쓰이므로 오류가 즉시 드러납니다. 어떤 하위 시스템에 대한 스무 쪽짜리 설명은 한 번 읽히고, 그 오류는 열여덟 달 뒤 누군가 그것을 근거로 움직일 때에야 드러납니다. 아무도 쓰지 않는 문서는 조용히 썩습니다. 그런 문서야말로 처음부터 쓰지 않는 편이 낫습니다.

왜 문서는 낡는가

세 가지 메커니즘이 있고, 그중 게으름은 하나뿐입니다.

문서가 설명 대상과 떨어진 곳에 삽니다. 코드를 바꾸는 일은 위키 문서를 바꾸는 일이 아니어서, 둘을 맞춰 두는 일은 누군가 기억해 내는 데 달려 있습니다. 그 기억은 어김없이 실패하고, 문서가 코드에서 멀리 있을수록 더 빨리 실패합니다.

의도가 아니라 구현을 설명합니다. 어떤 구성 요소가 지금 어떻게 동작하는지 설명하는 문서는 리팩터링이 일어날 때마다 무효가 됩니다. 그 구성 요소가 왜 존재하고 어떤 제약을 만족시키는지 설명하는 문서는 살아남습니다. 이유는 코드보다 훨씬 드물게 바뀌기 때문입니다.

주인이 없습니다. 모두의 것인 문서는 누구의 것도 아니고, 그 정확성이 특정한 누군가의 문제가 되는 순간이 끝내 오지 않습니다.

해법은 원인에서 곧바로 따라 나옵니다. 코드 가까이에 두고, 메커니즘 대신 의도를 쓰고, 문서마다 이름이 적힌 담당자와 그것을 실제로 쓰게 되는 계기를 붙여 주는 것입니다.

유지할 가치가 있는 기술 문서

네 가지 문서가 가치의 대부분을 덮습니다. 나머지는 스스로 존재 이유를 증명해야 합니다.

시스템을 돌아가게 만드는 README. 이것이 무엇인지, 어떻게 설정하는지, 테스트는 어떻게 돌리는지, 어떻게 배포하는지. 끊임없이 쓰이므로 오류가 빠르게 드러납니다. 어느 저장소에서든 수익률이 가장 높은 문서이면서, 동시에 아무도 손대지 않은 프로젝트 템플릿 그대로 방치되는 일이 가장 잦은 문서이기도 합니다.

아키텍처 개요. 큰 덩어리가 무엇이고, 서로 어떻게 통신하며, 왜 분리되어 있는지. 세부가 아니라 형태를 설명하는 한 쪽짜리 글과 그림 하나면 충분합니다. 좀처럼 바뀌지 않으면서, 그것이 없으면 새로 온 개발자마다 전부 읽어 가며 혼자 재구성해야 하는 질문에 답해 줍니다.

결정 기록. 어떤 결정과 검토한 대안, 그리고 그렇게 고른 이유를 붙잡아 두는 짧은 메모입니다. 업계에서는 보통 아키텍처 결정 기록, 줄여서 ADR이라고 부릅니다. 덧붙이기만 할 뿐 갱신할 일이 없고, 가장 비싼 종류의 반복 작업을 막아 줍니다. 이미 정리된 논의를, 그것을 정리했던 제약을 아무도 기억하지 못한 채 서툴게 다시 벌이는 일 말입니다.

고장 나는 것들을 위한 런북. 런북은 장애 대응 절차서입니다. 실제로 겪어 본 장애를 어떻게 진단하고 어떻게 고치는지 적습니다. 사건 직후 기억이 생생할 때 쓰고, 다음 사건에서 시험합니다. 아무도 따라가 본 적 없는 런북은 초안일 뿐입니다.

이 넷 중 어느 것도 코드가 어떻게 동작하는지를 설명하지 않는다는 점에 주목하십시오. 그것은 코드가 할 일이고, 코드를 되풀이하는 산문은 언젠가 첫 번째와 어긋날 두 번째 진실의 원천이 됩니다.

지치고 바쁜 사람을 위해 써라

기술 문서 대부분은 압박 속에서 읽힙니다. 아주 구체적인 질문을 가진 사람이, 대개 근무 시간이 아닌 때에 읽습니다. 여유 있는 독자가 아니라 그 독자를 위해 쓰십시오.

답을 먼저, 설명은 나중에. 새벽 두 시에 당신의 런북을 읽는 사람에게는 명령어가 먼저 필요하고 근거는 그다음입니다. 답보다 맥락을 앞세우는 구성은 글쓴이에게만 편하고 다른 누구에게도 편하지 않습니다.

구체적으로 쓰십시오. 진짜 명령어, 진짜 경로, 진짜 예시 값. “적절한 환경 변수를 설정하십시오”는 지시가 아니라 지시에 대한 설명일 뿐입니다.

무엇이 잘못될지 말하십시오. 실패 양상과 그것이 어떻게 보이는지가 가장 값진 내용인 경우가 많습니다. 독자가 지금 겪고 있는 것이 바로 그것이기 때문입니다.

참으로 남을 만큼 짧게 유지하십시오. 문장 하나하나가 유지보수 부채입니다. 흔한 경우를 다루면서 자기 한계를 인정하는 한 쪽이, 모든 것을 다루면서 세 군데가 틀린 문서보다 낫습니다.

검색 시스템이 인용할 만한 문서로 만드는 규율은 지친 동료가 쓸 수 있는 문서로 만드는 규율과 같습니다. 공개된 글에 관해 콘텐츠가 상위에 올라도 인용되지 않는 이유를 다룬 우리 글이 말하려는 바가 바로 이것입니다.

문서를 살아 있게 유지하기

저장소 안에 두십시오. 코드와 함께 움직이는 문서는 코드와 같은 리뷰에서 함께 고쳐집니다. 둘을 확실하게 맞춰 두는 유일한 방법입니다.

코드 리뷰에서 함께 보십시오. 어떤 변경이 문서를 틀리게 만든다면 그것은 다른 어떤 지적과도 다르지 않은 리뷰 코멘트입니다. 쓸 수 있는 습관 중 지렛대가 가장 큰 습관이고, 비용은 전혀 들지 않습니다.

테스트할 수 있는 것은 테스트하십시오. 파이프라인에서 실제로 실행되는 설치 절차는 더 이상 희망 사항이 아닙니다. README가 명령어 세 개면 돌아가는 시스템이 된다고 주장한다면, 잡 하나가 그것을 증명하게 하십시오.

과감하게 지우십시오. 틀린 문서는 없는 문서보다 나쁩니다. 사람들이 그것을 믿기 때문입니다. 무언가 낡았는데 아무도 고치지 않을 것이라면, 치우고 무엇이 사라졌는지 적어 두십시오.

만료되는 것에는 날짜를 붙이십시오. 버전 번호나 가격, 외부 의존성이 들어간 내용에는 날짜가 있어야 합니다. 그래야 독자가 그것을 믿어도 될지 스스로 판단합니다.

이것이 진짜로 필요한 이유

문서는 지식이 특정 개인에게 매달리는 상태를 끝내는 장치입니다. 이것이 이익의 전부이고, 그래서 문서를 쓰자는 주장은 미학이 아니라 사업의 논리입니다.

한 사람만 배포할 수 있는 시스템은 복구 시간이 그 사람의 가용성과 같아집니다. 아무도 설명하지 못하는 구성 요소는 다시 만들어지거나 미신처럼 보존됩니다. 둘 다 기술 실사에서 지적 사항으로 나오고, 둘 다 개발자 온보딩을 길게 만들며, 둘은 옷만 다르게 입은 같은 문제입니다.

Mecanik은 모든 프로젝트에서 인수인계의 일부로 이 문서들을 작성하며, 이는 소프트웨어 개발 업무의 일부입니다. 실제로 쓰이게 되는 문서는 거의 언제나 요청받았던 문서보다 짧습니다.

자주 묻는 질문

기술 문서는 왜 낡습니까? 코드와 떨어진 곳에 살아서 둘을 맞추는 일이 누군가의 기억에 달려 있고, 의도가 아니라 구현을 설명해서 리팩터링마다 무효가 되며, 주인이 없어서 정확성이 누구의 구체적인 책임도 되지 않기 때문입니다. 저장소 안에 두고 코드 변경과 함께 리뷰하면 세 가지 원인이 한꺼번에 해결됩니다.

소프트웨어 팀은 어떤 문서를 유지해야 합니까? 네 가지가 가치의 대부분을 덮습니다. 시스템을 돌아가게 만드는 README, 형태와 근거를 설명하는 한 쪽짜리 아키텍처 개요, 왜 그렇게 정했는지를 붙잡아 두는 덧붙이기 전용 결정 기록, 그리고 실제로 겪어 본 장애를 위한 런북입니다. 코드가 어떻게 동작하는지에 대한 설명은 이 목록에 없습니다.

결정 기록이란 무엇입니까? 어떤 결정과 검토한 대안, 그리고 그 선택의 이유를 적어 둔 짧은 메모입니다. 현재 상태가 아니라 한 시점을 기록하기 때문에 갱신할 일이 없고, 이미 정리된 문제를 그 제약을 기억하지 못하는 사람들이 서툴게 다시 논쟁하는 일을 막아 줍니다.

기술 문서는 어떻게 써야 합니까? 지치고 압박을 받으면서 딱 한 가지를 찾는 사람을 위해 씁니다. 답을 먼저 쓰고 설명은 나중에 하며, 설명 대신 진짜 명령어와 진짜 경로를 쓰고, 무엇이 잘못되고 그것이 어떻게 보이는지 말하고, 내용이 참으로 남을 만큼 짧게 유지합니다.

낡은 문서는 지워야 합니까? 아무도 고치지 않을 것이라면 지우십시오. 틀린 문서는 없는 문서보다 나쁩니다. 독자가 그것을 믿고 그대로 움직이기 때문입니다. 지우고 무엇이 사라졌는지 적어 두고, 버전 번호나 가격, 외부 의존성이 들어간 내용에는 날짜를 붙여 독자가 스스로 판단하게 하십시오.