들어가며: 말은 한 번, 문서는 백 번 읽힌다

LINE에서 일하던 시절, 한 동료가 퇴사하면서 남긴 위키 문서 하나가 두고두고 기억에 남습니다. 그가 떠난 뒤에도 그 문서는 살아남아, 신규 입사자가 들어올 때마다 다시 읽혔습니다. 1년 동안 그 문서를 읽은 사람이 수십 명이었습니다. 그는 그 문서를 단 한 번 썼는데, 그 글은 수십 번 일했습니다.

반대 경험도 있습니다. 어떤 기능을 누가, 왜, 어떻게 만들었는지 아무 기록이 없어서, 코드만 보고 한참을 추적해야 했던 적이 있습니다. 그 코드를 짠 사람은 이미 떠났고, 그가 머릿속에 가지고 있던 맥락은 함께 사라졌습니다. 그때 절감했습니다. 문서로 남기지 않은 지식은, 그것을 아는 사람이 떠나는 순간 함께 죽는다는 것을.

말은 휘발됩니다. 회의에서 아무리 명료하게 설명해도, 그 자리에 없던 사람에게는 닿지 않고, 그 자리에 있던 사람도 일주일 뒤면 절반을 잊습니다. 문서는 다릅니다. 문서는 잠들지 않고, 시차를 넘고, 사람이 떠난 뒤에도 남습니다.

이 글은 화려한 글쓰기 기법에 관한 것이 아닙니다. "다시 읽히는 글", 즉 시간이 지나도, 작성자가 곁에 없어도 제 역할을 하는 실용적인 문서를 쓰는 법에 관한 것입니다.

핵심 통찰: 문서는 협업과 인수인계의 중심이다

소프트웨어를 만드는 일은 본질적으로 협업입니다. 그리고 협업의 절반 이상은 "지식의 이동"입니다. 내 머릿속에 있는 것을 다른 사람의 머릿속으로 옮기는 일. 이 이동의 매개체가 바로 문서입니다.

문서가 중요한 이유는 세 가지 비대칭 때문입니다.

첫째, 시간의 비대칭입니다. 글은 한 번 쓰지만 여러 번, 여러 시점에 읽힙니다. 내가 쓰는 데 30분 더 들여서 읽는 사람 50명의 시간을 각 5분씩 아낀다면, 그것은 압도적으로 남는 투자입니다.

둘째, 공간의 비대칭입니다. 분산된 팀, 다른 시간대, 다른 사무실. 모두를 한 회의실에 모을 수 없습니다. 문서는 모두가 같은 정보에 접근할 수 있게 하는 유일하게 확장 가능한 수단입니다.

셋째, 인원의 비대칭입니다. 사람은 떠납니다. 이직하고, 부서를 옮기고, 휴가를 갑니다. 사람에게만 저장된 지식은 그 사람과 함께 사라집니다. 문서는 떠난 사람의 지식을 조직에 남깁니다.

> 코드는 "어떻게(how)"를 말한다. 문서는 "왜(why)"를 말한다. 그리고 6개월 뒤의 당신을 가장 괴롭히는 질문은 언제나 "왜"다.

그래서 좋은 문서는 친절한 인수인계입니다. 미래의 동료에게, 그리고 모든 것을 잊어버린 6개월 뒤의 자기 자신에게 보내는 편지입니다.

끊임없이 다시 읽히므로 섬세하게

여기서 핵심적인 관점 전환이 필요합니다. 문서는 "쓰는 것"이 아니라 "읽히는 것"입니다. 글의 가치는 작성하는 순간이 아니라, 읽히는 순간에 발생합니다.

이 관점에서 보면, 문서 작성의 비용 구조가 뒤집힙니다. 내가 글을 쓰는 데 드는 시간은 일회성입니다. 하지만 사람들이 그 글을 읽는 데 드는 시간은 읽는 횟수만큼 곱해집니다. 100명이 읽을 문서라면, 내가 문장을 1분 다듬어서 각자의 이해 시간을 10초씩만 줄여도, 전체적으로는 막대한 시간이 절약됩니다.

그래서 자주 읽히는 문서일수록 섬세하게 써야 합니다. 한 번 읽고 버릴 메모와, 수십 명이 두고두고 참조할 온보딩 가이드는 들여야 할 정성이 다릅니다.

작성자와 독자 사이에는 결정적인 정보 비대칭이 있습니다. 작성자는 모든 맥락을 머릿속에 가지고 있지만, 독자는 백지에서 출발합니다. 작성자에게 너무 당연해서 생략한 그 한 줄이, 독자에게는 글 전체를 이해하지 못하게 만드는 결정적인 구멍이 됩니다. 이것이 인지심리학에서 말하는 "지식의 저주(curse of knowledge)"입니다. 내가 아는 것을 남도 안다고 무의식적으로 가정하는 함정입니다.

섬세한 문서는 이 저주를 의식적으로 깨뜨립니다. "이 글을 처음 보는 사람이 이걸 이해할 수 있을까"를 끊임없이 자문합니다. 그것이 다시 읽히는 글의 출발점입니다.

좋은 문서의 구조: 목적·맥락·결론을 먼저

가장 흔하고 치명적인 실수는 "시간 순서대로" 쓰는 것입니다. 내가 알아간 순서대로, 즉 배경부터 시작해서 과정을 거쳐 결론으로 가는 방식입니다. 이건 작성자에게는 자연스럽지만 독자에게는 고문입니다. 독자는 결론을 빨리 알고 싶은데, 끝까지 읽어야 결론이 나오기 때문입니다.

좋은 문서는 결론을 먼저 둡니다. 신문 기사가 핵심을 첫 문단에 두는 "역피라미드(inverted pyramid)" 구조와 같습니다. 아마존이 내부에서 쓰는 6페이지 문서 문화나, "BLUF(Bottom Line Up Front, 결론부터)"라는 군대식 원칙도 같은 철학입니다.

권장하는 문서 골격은 이렇습니다.

[제목] — 무엇에 관한 문서인지 한눈에

1. 한 줄 요약 (TL;DR)

- 이 문서를 통해 알아야 할 단 하나

2. 목적 / 배경

- 왜 이 문서가 존재하는가

- 누가 읽어야 하는가

3. 결론 / 핵심 주장

- 무엇을 해야 하는가, 무엇이 결정되었는가

4. 근거 / 상세 설명

- 왜 그 결론에 이르렀는가

- 고려한 대안과 트레이드오프

5. 실행 / 다음 단계

- 구체적으로 누가 무엇을 언제

6. 참고 / 부록

- 관련 링크, 용어, 추가 자료

이 구조의 핵심은 "역피라미드"입니다. 가장 중요한 정보가 위에 있고, 아래로 갈수록 세부적입니다. 그래서 바쁜 독자는 위 세 항목만 읽고 떠날 수 있고, 깊이 알아야 하는 독자는 끝까지 읽을 수 있습니다. 같은 문서가 서로 다른 깊이의 독자를 모두 만족시키는 것입니다.

또 하나의 원칙: "왜"를 반드시 남기십시오. "무엇을 했는가"는 코드와 결과물에 남지만, "왜 그렇게 했는가"는 작성자의 머릿속에만 있습니다. 6개월 뒤 누군가 "이건 왜 이렇게 했지?"라고 물을 때, 그 답이 문서에 있다면 그 문서는 황금입니다. 특히 고려했지만 채택하지 않은 대안과 그 이유를 적어두면, 미래의 누군가가 같은 고민을 반복하는 것을 막아줍니다.

독자 배려: 누구를 위해 쓰는가

좋은 문서는 독자를 머릿속에 그리며 씁니다. "이 글의 첫 독자는 누구인가?"를 먼저 정해야 합니다.

독자에 따라 같은 내용도 다르게 써야 합니다.

| 독자 유형 | 그들이 원하는 것 | 문서가 강조할 것 |

| --- | --- | --- |

| 의사결정자 | 결론과 영향 | 요약, 비용, 리스크, 권고안 |

| 동료 개발자 | 구현 방법과 이유 | 설계 근거, 트레이드오프, 예시 코드 |

| 신규 입사자 | 전체 맥락 | 배경, 용어 정의, 단계별 안내 |

| 미래의 나 | 당시의 판단 근거 | 왜 이렇게 결정했는지, 대안 기록 |

독자 배려의 구체적인 실천은 이렇습니다.

첫째, 전문 용어를 처음 쓸 때 풀어줍니다. 약어는 처음 한 번 풀어쓰고 괄호로 약어를 병기합니다. 작성자에게 익숙한 내부 용어가 독자에게는 외계어일 수 있습니다.

둘째, 스캔 가능하게 만듭니다. 사람은 문서를 정독하지 않고 훑습니다. 제목, 굵은 글씨, 글머리표, 표를 활용해서 훑기만 해도 구조가 보이게 합니다. 한 문단이 다섯 줄을 넘으면 쪼개는 것을 고려하십시오.

셋째, 예시를 줍니다. 추상적인 설명 열 줄보다 구체적인 예시 하나가 낫습니다. 특히 "이렇게 하세요"와 "이렇게 하지 마세요"를 나란히 보여주면 이해가 극적으로 빨라집니다.

넷째, 독자의 다음 행동을 명확히 합니다. 문서를 다 읽은 독자가 "그래서 나는 뭘 해야 하지?"라고 묻지 않도록, 다음 단계를 분명히 적습니다.

비동기 소통: 문서가 회의를 대체할 때

문서는 비동기 소통(asynchronous communication)의 핵심 도구입니다. 비동기 소통이란 모두가 동시에 같은 자리에 있지 않아도 되는 소통입니다.

회의(동기 소통)는 강력하지만 비쌉니다. 참석자 전원의 시간을 같은 시각에 묶어야 하고, 한 번 지나가면 휘발되며, 발언권은 목소리 큰 사람에게 쏠리기 쉽습니다. 반면 잘 쓰인 문서는 각자 편한 시간에 읽고, 영구히 남으며, 글로 쓰면 모든 사람의 의견이 동등하게 기록됩니다.

GitLab과 같은 완전 원격 회사는 "문서 우선(documentation first)" 문화를 명시적으로 채택합니다. 핵심 원칙은 "회의를 열기 전에 먼저 문서를 쓰라"는 것입니다. 회의에서 처음 문제를 설명하지 말고, 미리 문서로 공유한 뒤 그 문서에 댓글로 비동기 토론을 진행합니다. 회의는 정말로 실시간 대화가 필요한, 즉 문서로 풀리지 않는 의견 충돌이 있을 때만 엽니다.

비동기 소통의 이점은 분명합니다.

- 깊이 생각할 시간이 생깁니다. 글로 답하려면 즉흥적 반응이 아니라 정리된 생각이 나옵니다.

- 시차와 일정에 자유롭습니다. 분산된 팀에 필수적입니다.

- 자동으로 기록이 남습니다. 토론 자체가 곧 문서가 됩니다.

- 내향적인 사람도 동등하게 참여합니다. 회의에서 말할 틈을 못 잡는 사람도, 글로는 충분히 기여합니다.

다만 비동기에도 한계가 있습니다. 감정이 얽힌 민감한 대화, 빠른 브레인스토밍, 복잡한 실시간 협의는 여전히 동기 소통이 낫습니다. 핵심은 둘 중 하나가 아니라 적절한 분배입니다. 정보 전달과 의사결정 기록은 문서로, 실시간 합의와 관계 형성은 대화로.

문서 템플릿: 바로 쓰는 골격들

매번 백지에서 시작하면 문서 쓰기가 부담스럽습니다. 자주 쓰는 문서는 템플릿을 만들어두면 문턱이 낮아지고 일관성이 생깁니다.

설계 문서 (Design Doc)

[제목] 설계 문서

TL;DR

- 한 줄 요약

배경 / 문제

- 무엇을 해결하려 하는가

목표 / 비목표

- 이 작업이 달성할 것 / 일부러 하지 않을 것

제안하는 방안

- 핵심 설계

고려한 대안

- 대안 A, B와 채택하지 않은 이유

리스크 / 영향 범위

- 예상되는 위험과 완화책

일정 / 다음 단계

- 누가, 무엇을, 언제

결정 기록 (ADR, Architecture Decision Record)

[번호]. [결정 제목]

상태

- 제안됨 / 채택됨 / 폐기됨

맥락

- 어떤 상황에서 이 결정이 필요했는가

결정

- 우리가 결정한 것

결과

- 이 결정으로 생기는 긍정적/부정적 영향

회의록 / 비동기 결정

[날짜] [주제]

결론 (먼저)

- 결정된 것 한눈에

액션 아이템

- [ ] 담당자 — 할 일 — 기한

논의 내용

- 핵심 논점 요약

템플릿의 목적은 형식을 강제하는 것이 아니라, "무엇을 빠뜨리지 말아야 하는지"를 일깨우는 것입니다. 특히 "고려한 대안"과 "결정의 이유"는 사람들이 가장 자주 빠뜨리지만 가장 가치 있는 항목입니다.

사례: 같은 정보, 다른 문서

추상적 원칙을 구체화해봅시다. 새 배포 절차를 공유하는 문서를 두 가지로 비교합니다.

방식 A — 작성자 중심

"지난주에 배포 관련해서 이슈가 좀 있었고, 그래서 여러 방안을 검토했는데, 처음엔 A를 생각했다가 B도 봤다가, 결국 논의 끝에 새 절차를 도입하기로 했습니다. 자세한 건 아래에..."

방식 B — 독자 중심

"요약: 오늘부터 배포는 반드시 스테이징을 거칩니다. 기존 방식과 다른 점은 단 하나, '스테이징 승인' 단계가 추가되었다는 것입니다.

대상: 배포 권한이 있는 모든 개발자

시행: 2026년 6월 19일부터

이유: 지난주 직접 배포로 인한 장애 재발 방지

새 절차 (3단계):

1. PR 머지

2. 스테이징 자동 배포 후 확인

3. 승인 버튼 클릭 → 프로덕션 배포

기존과 달라진 점만 보려면: 3번 승인 단계가 새로 생겼습니다."

방식 B가 우월한 이유는, 독자가 알아야 할 것을 독자의 순서로 배치했기 때문입니다. 결론 먼저, 대상과 시점 명확히, 변경점만 콕 집어서. 독자는 자기에게 필요한 부분만 빠르게 찾아 떠날 수 있습니다.

함정: 과한 문서화를 경계하라

지금까지 문서의 가치를 강조했지만, 균형이 필요합니다. 문서화는 도구이지 목적이 아닙니다. 과한 문서화는 부족한 문서화만큼이나 해롭습니다.

함정 1: 아무도 안 읽는 문서

만들기 위해 만든 문서, 형식을 채우기 위한 문서는 비용만 발생시킵니다. 모든 것을 문서화하려 하면 정작 중요한 문서가 노이즈에 묻힙니다. 문서를 쓰기 전에 물으십시오. "이걸 누가, 언제, 왜 다시 읽을까?" 답이 없으면 쓰지 마십시오.

함정 2: 낡아버린 문서 (Documentation Rot)

가장 위험한 문서는 없는 문서가 아니라 틀린 문서입니다. 코드는 바뀌었는데 문서는 옛날 그대로라면, 그 문서는 독자를 적극적으로 오도합니다. 유지보수할 수 없는 문서는 차라리 안 쓰는 게 낫습니다. 그래서 "어디에 무엇이 있는지"를 가리키는 가벼운 인덱스 문서가, 모든 세부를 담은 무거운 문서보다 오래 살아남는 경우가 많습니다.

함정 3: 문서가 코드를 중복

코드를 그대로 한국어로 옮긴 주석이나 문서는 가치가 없습니다. 코드가 "어떻게"를 이미 말하고 있다면, 문서는 "왜"에 집중해야 합니다.

함정 4: 완벽주의로 인한 마비

완벽한 문서를 쓰려다 아무것도 안 쓰는 것보다, 70%짜리 문서라도 있는 게 낫습니다. 문서는 살아있는 것이고, 나중에 고칠 수 있습니다. "초안이지만 공유합니다"가 "완벽할 때까지 비공개"보다 거의 항상 낫습니다.

균형점은 이렇습니다. 자주 읽히고, 오래 쓰이고, 사람이 떠나면 사라질 지식 — 이런 것을 문서로 남기십시오. 한 번 쓰고 말 것, 코드에 이미 명백한 것, 곧 바뀔 것은 문서화하지 마십시오.

쓰는 과정: 초안과 퇴고는 다른 일이다

좋은 문서는 단번에 나오지 않습니다. 글쓰기를 어려워하는 사람들의 흔한 착각은, 머릿속에서 완벽한 문장을 만들어 한 번에 써 내려가려 한다는 것입니다. 그러면 첫 문장에서부터 막힙니다. 글쓰기는 두 개의 분리된 작업입니다. 첫째는 생각을 쏟아내는 일(초안), 둘째는 그것을 다듬는 일(퇴고)입니다. 이 둘을 동시에 하려는 것이 글쓰기를 고통스럽게 만드는 주범입니다.

작가들이 흔히 인용하는 원칙이 있습니다. "초안은 형편없어도 된다(write drunk, edit sober)"는 정신, 즉 초안은 빠르고 거칠게, 퇴고는 차갑고 냉정하게. 초안 단계에서는 맞춤법도, 문장 다듬기도 잊고 그냥 머릿속의 것을 다 꺼냅니다. 구조가 엉망이어도 괜찮습니다. 일단 재료가 있어야 다듬을 수 있습니다.

퇴고 단계가 문서의 질을 결정합니다. 퇴고할 때는 작성자가 아니라 독자의 눈으로 읽습니다. 특히 다음을 점검합니다.

- 결론이 위에 있는가, 아니면 끝까지 읽어야 나오는가

- 한 문장에 여러 생각이 엉켜 있지 않은가 (한 문장 한 생각)

- 처음 보는 사람이 막힐 지점은 어디인가

- 빼도 의미가 통하는 군더더기는 무엇인가

특히 마지막, "빼도 되는 것을 빼는 것"이 퇴고의 핵심입니다. 프랑스 작가 생텍쥐페리는 "완벽함이란 더 보탤 것이 없을 때가 아니라, 더 뺄 것이 없을 때 이루어진다"고 했습니다. 좋은 문서는 길어서가 아니라 짧아서 좋습니다. 독자의 시간은 비싸고, 군더더기는 그 시간을 훔칩니다.

한 가지 실용적인 팁: 발행 전에 소리 내어 읽어보거나, 하루 묵혔다가 다시 보십시오. 쓸 때는 안 보이던 어색함과 구멍이 시차를 두면 보입니다. 그리고 가능하면 동료에게 "처음 보는데 이해돼?"라고 물어보십시오. 지식의 저주를 깨는 가장 확실한 방법은 실제 독자의 눈입니다.

문서가 사는 곳: 발견 가능성의 문제

아무리 잘 쓴 문서도 아무도 찾지 못하면 없는 것과 같습니다. 문서화의 숨은 절반은 "발견 가능성(discoverability)"입니다. 문서가 어디에 있는지, 어떻게 검색되는지가 내용만큼 중요합니다.

흔한 실패는 문서가 여기저기 흩어지는 것입니다. 누구는 위키에, 누구는 슬랙 메시지에, 누구는 개인 메모에 적습니다. 그 결과 같은 질문이 반복되고, 이미 있는 답을 못 찾아 다시 만듭니다. 정보의 중복과 모순이 쌓입니다.

발견 가능성을 높이는 실천은 이렇습니다.

- 단일 진실 공급원(single source of truth)을 정한다. "이 주제는 여기에 있다"는 합의된 장소.

- 검색되는 제목을 쓴다. 사람들이 실제로 검색할 단어를 제목에 넣는다.

- 인덱스 문서를 둔다. "무엇이 어디 있는지"를 가리키는 가벼운 허브 문서.

- 관련 문서끼리 링크로 연결한다. 하나를 찾으면 인접한 것들로 이어지게.

여기서 앞서 말한 "낡은 문서"의 문제가 다시 등장합니다. 검색은 잘 되는데 내용이 틀린 문서가 가장 위험합니다. 그래서 발견 가능성과 최신성은 함께 가야 합니다. 오래된 문서에는 "마지막 업데이트: 날짜"를 명시하거나, 더 이상 유효하지 않으면 명시적으로 "보관됨(archived)" 표시를 하는 것이 좋습니다.

숨은 효용: 쓰면서 생각이 정리된다

문서의 가치를 "남에게 전달하는 것"으로만 보면, 절반을 놓치는 것입니다. 문서를 쓰는 행위 자체가 생각을 정리하는 강력한 도구입니다. 즉, 문서는 독자뿐 아니라 작성자에게도 이득입니다.

머릿속에서 안다고 느끼던 것을 막상 글로 쓰려 하면, 곳곳에서 막힙니다. "어, 이 부분은 사실 내가 명확히 모르고 있었구나", "이 두 단계 사이에 논리적 비약이 있네". 글쓰기는 생각의 구멍을 가차 없이 드러냅니다. 말로는 얼버무릴 수 있지만, 글은 얼버무림을 허락하지 않습니다.

이것을 "글쓰기는 생각의 디버깅"이라고 부를 수 있습니다. 모호한 생각은 모호한 글이 됩니다. 글이 명료해지지 않는다면, 그건 보통 글솜씨의 문제가 아니라 생각이 아직 명료하지 않다는 신호입니다. 그래서 설계를 코드로 옮기기 전에 설계 문서를 먼저 쓰면, 구현 단계에서 마주칠 문제의 상당수를 미리 발견합니다.

아마존이 회의에서 슬라이드 대신 6페이지 서술형 메모를 쓰게 하는 이유가 여기 있습니다. 제프 베이조스는 글로 된 서술이 "더 명확하게 생각하도록 강제한다"고 했습니다. 불릿 포인트는 논리의 빈틈을 숨길 수 있지만, 완전한 문장으로 된 서술은 그 빈틈을 드러냅니다.

그러니 문서를 "어쩔 수 없이 해야 하는 부수 작업"으로 여기지 마십시오. 중요한 일을 시작하기 전에 한 페이지라도 써보는 것은, 남을 위한 일이기 전에 자신의 생각을 명료하게 하는 일입니다. 종종 그 과정에서, 글을 쓰기 전엔 보이지 않던 더 나은 방향이 떠오릅니다.

자주 묻는 질문 (FAQ)

대개 초안과 퇴고를 동시에 하려 하기 때문입니다. 한 문장을 완벽하게 다듬으며 다음으로 넘어가지 못하는 것이죠. 먼저 거칠게 다 쏟아낸 뒤 다듬으십시오. 또 하나, 매번 백지에서 시작하지 말고 템플릿을 쓰십시오. 그리고 모든 문서가 정성을 똑같이 들일 필요는 없습니다. 자주 읽힐 문서에만 깊이 투자하고, 일회성 메모는 가볍게 쓰는 분별이 시간을 아낍니다.

회의는 그 순간 빠릅니다. 하지만 휘발됩니다. 그 자리에 없던 사람, 일주일 뒤 잊어버린 사람, 6개월 뒤 들어온 사람에게는 닿지 않습니다. 회의가 빠른 것은 "지금 그 자리에 있는 사람들"에게만입니다. 결정과 정보 전달은 문서가, 실시간 합의와 토론은 회의가 낫습니다. 가장 좋은 조합은 "회의 전 문서로 맥락 공유, 회의에선 결정, 회의 후 문서로 결정 기록"입니다.

세 가지를 점검하십시오. 첫째, 결론이 위에 있습니까? 끝까지 읽어야 핵심이 나오면 사람들은 중간에 떠납니다. 둘째, 찾을 수 있습니까? 발견 가능성 문제일 수 있습니다. 셋째, 정말 필요한 문서입니까? 아무도 안 읽는다면 애초에 쓸 필요가 없었을 수도 있습니다. 읽히지 않는 문서는 종종 내용이 아니라 구조나 위치의 문제입니다.

주석과 문서는 역할이 다릅니다. 주석은 "이 코드가 무엇을 하는가"의 가까운 맥락에 좋지만, "왜 이 시스템을 이렇게 설계했는가", "어떤 대안을 고려했는가" 같은 큰 그림은 담기 어렵습니다. 또 주석은 코드를 읽는 사람에게만 닿습니다. 의사결정자나 신규 입사자는 코드를 읽지 않습니다. 코드 주석은 "how"의 가까운 맥락, 문서는 "why"의 큰 맥락 — 둘 다 필요합니다.

문서 작성 체크리스트

문서를 발행하기 전, 다음을 점검하십시오.

- 첫 줄을 읽고 "무엇에 관한 문서"인지 알 수 있는가

- TL;DR 또는 결론이 맨 위에 있는가

- "왜"가 적혀 있는가 (무엇뿐 아니라)

- 처음 보는 독자가 이해할 수 있는가 (지식의 저주 점검)

- 약어와 전문 용어를 풀어줬는가

- 훑어보기만 해도 구조가 보이는가 (제목, 목록, 표)

- 독자의 다음 행동이 명확한가

- 고려했지만 채택하지 않은 대안을 적었는가

- 6개월 뒤에도 누군가 유지보수할 수 있는가

- 이 문서를 정말 누군가 다시 읽을 것인가 (아니면 회의가 나았을까)

한 가지 더: 그림과 표의 힘

긴 글이 항상 최선은 아닙니다. 어떤 정보는 글보다 그림이나 표로 전할 때 훨씬 빠르게 이해됩니다. "백문이 불여일견"은 문서에도 적용됩니다.

특히 다음 정보는 시각화가 강력합니다.

- 구조와 관계: 시스템 아키텍처, 데이터 흐름, 컴포넌트 간 의존성 — 다이어그램 하나가 세 문단을 대체합니다.

- 비교: 여러 선택지의 장단점은 표로 나란히 두면 한눈에 들어옵니다.

- 순서와 단계: 프로세스나 절차는 번호 목록이나 순서도가 줄글보다 명확합니다.

- 시간 흐름: 일정이나 변화는 타임라인으로.

다만 시각화에도 함정이 있습니다. 첫째, 유지보수 비용입니다. 그림은 글보다 고치기 번거로워서, 내용이 바뀌어도 방치되기 쉽습니다. 그래서 자주 바뀌는 내용은 차라리 글로 두는 게 나을 때가 있습니다. 둘째, 화려함의 함정입니다. 예쁜 다이어그램을 만드느라 정작 내용에 쓸 시간을 빼앗기지 마십시오. 거친 손그림이라도 핵심을 전달하면 충분합니다.

핵심 원칙은 "각 정보에 맞는 형식을 고르는 것"입니다. 모든 것을 줄글로 쓰지도, 모든 것을 그림으로 그리지도 마십시오. 구조는 그림으로, 비교는 표로, 맥락과 이유는 글로 — 정보의 성격에 맞는 그릇을 고르는 것이 독자를 배려하는 또 하나의 방법입니다.

마치며: 미래에게 보내는 편지

다시 LINE에서의 그 위키 문서로 돌아갑니다. 떠난 동료의 그 문서가 오래 기억에 남은 이유는, 그것이 단지 잘 쓴 글이어서가 아닙니다. 그가 자기가 떠난 뒤를 생각하며, 만난 적 없는 미래의 동료를 배려하며 썼다는 게 느껴졌기 때문입니다.

문서를 쓴다는 것은 시간을 거슬러 사람을 돕는 일입니다. 지금 30분을 들여, 6개월 뒤의 누군가가 헤매는 한나절을 아껴줍니다. 작성자가 떠난 자리에서도, 그 글은 계속 일합니다.

좋은 문서는 화려할 필요가 없습니다. 다만 다시 읽혀야 합니다. 결론을 먼저 두고, 왜를 남기고, 처음 보는 사람을 배려하고, 정말 필요한 것만 적는 것 — 그것이 다시 읽히는 글의 전부입니다.

그리고 기억하십시오. 완벽한 문서를 기다리느라 아무것도 남기지 않는 것보다, 70%짜리라도 지금 남기는 것이 거의 항상 낫습니다. 문서는 살아있는 것이고, 다음 사람이 고치고 보탤 수 있습니다. 첫 문장을 쓰는 것이 가장 어렵습니다. 일단 시작하면, 생각은 글을 따라 정리됩니다.

당신이 오늘 쓰는 문서는, 당신이 잊어버린 뒤에도 당신을 대신해 말할 것입니다. 그러니 미래의 독자에게 친절한 편지를 쓰십시오. 그 독자에는 6개월 뒤의 당신 자신도 포함됩니다.

참고 자료

- Larson, W. _An Elegant Puzzle: Systems of Engineering Management_ (2019) 및 lethain.com (https://lethain.com).

- GitLab Handbook, "Documentation" and "All Remote" (https://handbook.gitlab.com).

- Heath, C. and Heath, D. (2007). _Made to Stick_. Random House. (지식의 저주 개념)

- Amazon's "6-page narrative memo" 문화 — Harvard Business Review (https://hbr.org).

- Nielsen Norman Group, "How Users Read on the Web" (https://www.nngroup.com).

- Architecture Decision Records (ADR), Michael Nygard (https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions).