- 왜 이것이 승진보다 먼저 오는가
- 글은 조직 안에서 무엇을 하는가
- 설계 문서 — 남는 것은 버린 대안입니다
- 사고 보고서 — 사실과 해석을 나누기
- 리뷰 코멘트 — 등급을 붙이면 갈등이 줄어듭니다
- 글이 싸질 때 무엇이 값이 오르는가
- 직접 해보기
- 이어서 읽기
- 참고 자료
왜 이것이 승진보다 먼저 오는가
엔지니어에게 글쓰기가 중요하다는 조언은 대개 이렇게 끝납니다. 잘 써야 평가에서 인정받는다는 것입니다. 틀린 말은 아니지만 순서가 뒤집혀 있습니다.
순서를 바로 놓으면 이렇게 됩니다. 글은 먼저 자기 사고를 검증하는 장치입니다. 그다음 조직 안에서 반박 가능한 표면을 만드는 도구입니다. 그리고 그 두 가지의 결과로 평가에 영향을 줍니다. 세 번째만 보고 접근하면 문서가 홍보물이 되고, 홍보물은 조직에서 빠르게 할인됩니다.
첫 번째가 핵심입니다. 설명이 안 되는 설계는 대개 이해되지 않은 설계입니다. 머릿속에서는 매끄럽던 것이 문장으로 옮기는 순간 빈 곳을 드러냅니다. 그래서 쓰기는 표현 능력이기 이전에 자기 이해에 대한 검사입니다.
글은 조직 안에서 무엇을 하는가
세 가지 일을 합니다.
하나는 비동기 확장입니다. 회의는 참석자 수만큼 시간이 곱해지지만 문서는 읽는 사람이 늘어도 저자의 시간을 더 쓰지 않습니다. 열 명이 한 시간 회의하면 열 시간이고, 같은 내용을 문서로 만들면 저자가 두 시간을 쓰고 아홉 명이 각자 십오 분을 씁니다.
다른 하나는 시간 이동입니다. 문서는 3년 뒤의 사람에게 말을 겁니다. 그때 그 사람이 알고 싶은 것은 무엇이 만들어졌는지가 아니라 왜 그렇게 만들어졌는지입니다.
세 번째가 가장 중요합니다. 글은 반박 가능한 표면을 만듭니다. 말로 한 주장은 반박하려면 그 자리에서 즉석으로 반응해야 하고, 대개 목소리가 큰 쪽이 이깁니다. 문서에 적힌 주장은 각자 시간을 들여 검토할 수 있고, 반대 의견을 정리해 올 수 있습니다. 좋은 문서는 자기 주장을 관철하는 도구가 아니라, 자기 주장이 틀렸을 때 그 사실을 빨리 알게 되는 도구입니다.
설계 문서 — 남는 것은 버린 대안입니다
설계 문서에서 시간이 지나면 대부분의 내용이 낡습니다. 구조도는 바뀌고, 인터페이스는 달라지고, 일정은 안 맞습니다. 3년 뒤에도 값어치가 남는 부분은 거의 하나뿐입니다. 버린 대안과 버린 이유입니다.
이유는 3편에서 다룬 것과 같습니다. 코드는 채택된 안만 보여 주고 대안은 안 보여 줍니다. 그래서 나중에 온 사람이 "이거 그냥 이렇게 하면 되잖아"라고 말하는 일이 반복되고, 그 방식은 대개 이미 검토되고 버려진 것입니다.
그리고 반드시 표시해야 할 것이 하나 더 있습니다. 되돌릴 수 없는 결정입니다. 데이터 형식, 외부에 공개하는 인터페이스, 저장소 선택처럼 나중에 바꾸는 비용이 급격히 커지는 항목은 문서에서 눈에 띄게 분리해야 합니다. 이 표시가 있으면 리뷰어들이 어디에 시간을 쓸지 알게 되고, 없으면 되돌릴 수 있는 것들에 대한 논쟁으로 리뷰 시간이 다 갑니다.
사고 보고서 — 사실과 해석을 나누기
장애 보고서에서 가장 흔한 실패는 문장 안에서 사실과 해석이 섞이는 것입니다. "캐시 설정이 잘못되어 있어서 장애가 났다"는 문장에는 관측된 사실과 인과 주장이 붙어 있고, 붙어 있으면 둘 다 검증되지 않습니다.
나누면 이렇게 됩니다. 사실은 시간순으로만 적습니다. 몇 시 몇 분에 어떤 알림이 왔고, 무엇이 확인됐고, 무엇을 했고, 언제 회복됐는지. 해석은 별도 절에서 하고, 각 해석에는 어떤 사실이 근거인지를 붙입니다. 이렇게 하면 읽는 사람이 해석에 동의하지 않아도 사실은 공유할 수 있습니다.
여기에 붙는 원칙이 비난 없이 쓰기입니다. Google의 SRE 책은 이를 관련된 모두가 좋은 의도를 가지고 그 시점에 가진 정보로 옳은 일을 했다고 전제하는 것이라고 설명합니다. 그리고 그 이유를 도덕이 아니라 실용으로 제시합니다. 비난하는 분위기에서는 문제가 밖으로 나오지 않고 덮이며, 덮이면 조직의 위험이 커진다는 것입니다. 같은 책은 사람은 고칠 수 없지만 시스템과 절차는 고칠 수 있다는 문장으로 이 원칙을 정리합니다.
이건 예의의 문제가 아니라 정보 수집의 문제입니다. 비난이 예상되는 보고서에서는 사람들이 자기가 한 일을 정확히 말하지 않고, 정확하지 않은 사실 위에서는 어떤 개선도 설계할 수 없습니다.
리뷰 코멘트 — 등급을 붙이면 갈등이 줄어듭니다
리뷰에서 마찰이 생기는 큰 원인은 코멘트의 무게가 전달되지 않는 것입니다. 작성자는 모든 코멘트를 요구로 받고, 리뷰어는 가벼운 제안이었다고 생각합니다.
해법은 단순합니다. 코멘트마다 등급을 붙이는 것입니다.
예시 — 코멘트 앞에 붙이는 세 가지 표시
[막음] 이 상태로 병합하면 문제가 생깁니다. 근거: 동시 요청에서 잔액이 음수가 됩니다
[제안] 이 부분은 이렇게 하면 더 읽기 쉬울 것 같습니다. 안 바꿔도 병합 가능합니다
[취향] 저라면 다르게 쓰겠지만 옳고 그름의 문제는 아닙니다
이 표시 하나로 리뷰 시간이 크게 줄어듭니다. 작성자가 무엇에 먼저 답해야 할지 알고, 취향 코멘트 때문에 병합이 지연되지 않습니다.
그리고 내용 쪽에는 한 가지 규칙이 있습니다. 요구가 아니라 관찰과 근거를 씁니다. "이거 바꾸세요"보다 "동시 요청이 두 개 들어오면 여기서 잔액이 음수가 될 것 같은데 맞나요"가 낫습니다. 후자는 리뷰어가 틀렸을 가능성을 열어 두고, 열어 두면 실제로 리뷰어가 틀렸을 때 대화가 빨리 끝납니다.
글이 싸질 때 무엇이 값이 오르는가
여기서 정직해야 할 부분이 있습니다. 문장을 만들어 내는 일은 눈에 띄게 싸졌습니다. 그래서 "잘 쓴 문서"의 희소성은 예전 같지 않습니다.
그러면 무엇이 남느냐. 두 가지로 보입니다. 하나는 무엇을 쓸지 정하는 판단입니다. 이 결정에서 되돌릴 수 없는 것이 무엇인지, 어떤 대안이 진짜 경쟁자였는지, 어떤 사실을 아직 모르는지를 아는 것은 문장 생산과 다른 능력입니다. 다른 하나는 서명입니다. 문서에 이름을 걸고 그 결정의 결과를 감당하는 사람이 누구인지는 위임되지 않습니다.
다만 이 부분은 확신을 갖고 말하기 어렵습니다. 조직들이 문서를 어떻게 다룰지, 서명의 무게가 실제로 어떻게 변할지는 아직 정해지지 않은 영역입니다. 지금 말할 수 있는 것은 문장의 생산이 싸진 것은 확실하고, 그 문장이 담은 판단의 검증은 싸지지 않았다는 정도입니다.
직접 해보기
이번 주에 자기가 최근에 내린 기술적 결정 하나를 고르고, 그것에 대해 세 문단만 적어 보세요. 채택한 안, 검토했다 버린 대안 두 개와 버린 이유, 그리고 이 결정에서 되돌리기 어려운 부분. A4 반 장이면 충분하고, 이걸 적는 데 30분 이상 걸린다면 그 결정은 아직 정리되지 않은 것입니다.
- 사고력 훈련소 — 문제를 자기 말로 다시 쓰는 것이 첫 번째 수로 들어 있습니다. 설계 문서의 첫 문단이 하는 일과 정확히 같습니다.
안 통하는 경우도 적어 둡니다. 결정권자가 문서를 읽지 않는 조직에서는 긴 문서가 아무 일도 하지 않습니다. 그런 곳에서는 문서를 회의 5분 전에 읽을 수 있는 한 장 요약으로 압축하고, 긴 버전은 나중에 오는 사람을 위한 기록으로만 남기는 편이 낫습니다.
이어서 읽기
- 이 블로그의 관련 글: 글로 설득하기 — 디자인 문서와 RFC가 통과되는 구조
비싸게 남는 기술 시리즈
참고 자료
- Postmortem Culture — Google SRE Book — 비난 없이 쓴 보고서는 관련된 모두가 좋은 의도로 그 시점의 정보에 따라 옳은 일을 했다고 전제한다는 정의, 비난하는 분위기가 문제를 덮게 만든다는 논거, 사람은 고칠 수 없지만 시스템과 절차는 고칠 수 있다는 문장이 여기서 나옵니다. 2026-08-15 확인.
- 코멘트 등급 표시와 설계 문서의 우선순위 정리는 위 자료에 나오는 것이 아니라 이 글에서 정리한 방식입니다.
현재 단락 (1/34)
엔지니어에게 글쓰기가 중요하다는 조언은 대개 이렇게 끝납니다. 잘 써야 평가에서 인정받는다는 것입니다. 틀린 말은 아니지만 순서가 뒤집혀 있습니다.