코드보다 README가 더 길고, 주석 없는 코드는 죄악이다. 6개월 후의 동료를 위해 오늘도 설명을 남긴다.
문서화 신봉자(DOCS) 유형은 지식이 코드만큼이나 중요하다는 것을 누구보다 잘 아는 개발자입니다. 이들에게 코드는 절반의 작업물에 불과합니다. 나머지 절반은 그 코드가 왜 그렇게 작성되었는지, 어떻게 사용해야 하는지, 어떤 상황에서 한계가 있는지를 기록하는 것입니다. 주석 없는 함수를 보면 불안해지고, API 문서 없는 엔드포인트를 만나면 직접 문서를 쓰기 시작합니다.
DOCS 유형이 만든 프로젝트에는 반드시 훌륭한 README가 있습니다. 설치 방법, 환경 설정, 예제 코드, FAQ, 기여 가이드, 라이선스까지 빠짐없이 갖춰져 있습니다. 코드를 변경할 때 문서 업데이트를 빠뜨리면 심리적 불편감을 느끼며, 팀원들도 자연스럽게 문서 작성 문화에 동화됩니다. 이들의 노력 덕분에 새 팀원의 온보딩 시간이 크게 단축되고, 6개월 후 레거시 코드 파악도 훨씬 쉬워집니다.
이 유형은 Architecture Decision Record(ADR)라는 문화를 팀에 심으려 합니다. 왜 이 기술 스택을 선택했는지, 왜 이 DB 구조로 갔는지, 왜 이 라이브러리를 채택했는지를 문서로 남겨야 한다고 강하게 믿습니다. 그래야 1년 후 "왜 이렇게 했지?"라는 질문이 나왔을 때 근거를 찾을 수 있으니까요. Swagger, OpenAPI Spec, Storybook, Notion, Confluence — 문서화 도구라면 뭐든 능숙하게 다룹니다.
하지만 DOCS 유형에게도 그림자가 있습니다. 문서를 완벽하게 작성하려다 실제 구현이 늦어지는 경우가 있습니다. 코드 한 줄 추가할 때마다 주석을 추가하고, 변수명 하나를 바꿀 때도 설명을 업데이트합니다. PR에 코드 변경보다 주석 추가가 더 많을 때도 있습니다. 팀원 중 빠른 실행을 원하는 HACK 유형과 마찰이 잦은 이유이기도 합니다. 그러나 장기적으로 팀의 지식 자산을 쌓는 데 없어서는 안 될 존재입니다.
DOCS 유형이 팀에 가져오는 가장 큰 가치는 지식의 민주화입니다. 특정 사람만 알고 있는 암묵지가 문서로 남겨지면서, 팀 전체가 그 지식에 접근할 수 있게 됩니다. 핵심 개발자가 팀을 떠나더라도 시스템이 흔들리지 않는 것, 새 팀원이 2주 만에 독립적으로 작업할 수 있는 것이 DOCS 유형이 만들어내는 환경입니다.
도구 선택에도 철학이 있습니다. Markdown 기반의 문서는 코드와 함께 버전 관리가 가능하다는 점에서 선호합니다. Notion, Confluence보다 코드 레포 안의 docs 폴더를 더 신뢰하는 이유입니다. API 문서는 OpenAPI Spec으로 자동 생성하고, 코드 주석은 JSDoc, docstring으로 표준화합니다. 문서가 코드와 동기화되어야 한다는 원칙이 이들의 핵심 신념입니다.
DOCS 유형의 성장 과제는 '좋은 문서'와 '충분한 문서'의 균형입니다. 모든 것을 문서화하려는 욕심이 오히려 문서의 유지보수 부담을 키울 수 있습니다. 자주 변하는 구현 세부 사항보다 안정적인 개념과 결정의 이유를 기록하는 것이 장기적으로 더 가치 있습니다.
커리어 측면에서 DOCS 유형은 테크니컬 라이터, 개발자 에반젤리스트, 플랫폼 엔지니어링 등 문서화 역량이 핵심인 역할에서 두각을 나타냅니다. 오픈소스 프로젝트에서 좋은 문서를 작성한 사람이 컨트리뷰터들을 이끄는 중심이 되는 경우도 많습니다. 글쓰기 능력과 기술 이해도를 동시에 가진 희귀한 유형입니다.
"6개월 후의 내가 이 코드를 보게 될 거예요. 그때 내가 욕하지 않도록 지금 충분히 설명해두는 게 저에 대한 예의죠. 미래의 동료에게도 마찬가지고요."
— DOCS 유형 백엔드 개발자DOCS 유형이 팀에 합류한 첫 주, 그리고 6개월 후의 풍경을 비교해봅니다.
DOCS 유형이 있는 팀은 지식 자산이 빠르게 쌓입니다. 신규 팀원의 온보딩 시간이 절반으로 줄고, 담당자 부재 시에도 문서를 참고해 업무가 돌아갑니다. API 문서가 잘 되어 있어 프론트엔드-백엔드 커뮤니케이션 비용이 크게 낮아집니다. 의사결정 기록이 남아 있어 기술 부채가 생긴 이유를 추적할 수 있고, 같은 실수를 반복하지 않게 됩니다. 코드리뷰에서 논리적 근거가 명확하고, 외부 기여자가 프로젝트에 참여하기 쉬운 환경을 만듭니다.
문서가 코드보다 앞서면 실제 구현 속도가 떨어집니다. 아직 확정되지 않은 스펙을 문서로 먼저 써두었다가 요구사항이 바뀌면 문서와 코드가 따로 노는 상황이 발생하기도 합니다. 또한 모든 것을 문서화하려는 경향이 유지보수 부담으로 이어질 수 있습니다. '살아있는 문서(living documentation)' 관점으로 접근해, 코드 자체가 문서가 되도록 변수명과 함수명을 명확하게 짓는 것을 먼저 고려하는 것도 좋은 방법입니다.
Q. 문서화가 귀찮게 느껴지는 팀원을 어떻게 설득하나요?
PR 체크리스트에 '관련 문서 업데이트 여부' 항목을 추가하면 자연스럽게 문화가 형성됩니다. 6개월 된 코드를 문서 없이 이해해야 했던 고통스러운 경험을 공유하는 것도 효과적입니다.
Q. 어떤 것을 우선 문서화해야 하나요?
신규 팀원이 가장 자주 묻는 질문 TOP 5가 우선순위입니다. 온보딩 과정에서 막히는 지점이 곧 문서화가 필요한 지점입니다.
Q. 문서가 코드와 달라지면 어떻게 하나요?
자동화가 답입니다. API 문서는 코드에서 자동 생성하고, README의 버전 정보는 CI에서 자동 업데이트하세요. 사람이 수동으로 동기화하는 구조는 결국 무너집니다.
💡 문서를 쓰기 전에 '이 문서를 읽을 사람이 누구인가'를 먼저 정하세요. 독자가 명확하면 무엇을 포함하고 무엇을 생략할지가 자연스럽게 결정됩니다.