코드보다 README가 더 길고, 주석 없는 코드는 죄악이다. 6개월 후의 동료를 위해 오늘도 설명을 남긴다.
문서화 신봉자(DOCS) 유형은 지식이 코드만큼이나 중요하다는 것을 누구보다 잘 아는 개발자입니다. 이들에게 코드는 절반의 작업물에 불과합니다. 나머지 절반은 그 코드가 왜 그렇게 작성되었는지, 어떻게 사용해야 하는지, 어떤 상황에서 한계가 있는지를 기록하는 것입니다. 주석 없는 함수를 보면 불안해지고, API 문서 없는 엔드포인트를 만나면 직접 문서를 쓰기 시작합니다.
DOCS 유형이 만든 프로젝트에는 반드시 훌륭한 README가 있습니다. 설치 방법, 환경 설정, 예제 코드, FAQ, 기여 가이드, 라이선스까지 빠짐없이 갖춰져 있습니다. 코드를 변경할 때 문서 업데이트를 빠뜨리면 심리적 불편감을 느끼며, 팀원들도 자연스럽게 문서 작성 문화에 동화됩니다. 이들의 노력 덕분에 새 팀원의 온보딩 시간이 크게 단축되고, 6개월 후 레거시 코드 파악도 훨씬 쉬워집니다.
이 유형은 Architecture Decision Record(ADR)라는 문화를 팀에 심으려 합니다. 왜 이 기술 스택을 선택했는지, 왜 이 DB 구조로 갔는지, 왜 이 라이브러리를 채택했는지를 문서로 남겨야 한다고 강하게 믿습니다. 그래야 1년 후 "왜 이렇게 했지?"라는 질문이 나왔을 때 근거를 찾을 수 있으니까요. Swagger, OpenAPI Spec, Storybook, Notion, Confluence — 문서화 도구라면 뭐든 능숙하게 다룹니다.
하지만 DOCS 유형에게도 그림자가 있습니다. 문서를 완벽하게 작성하려다 실제 구현이 늦어지는 경우가 있습니다. 코드 한 줄 추가할 때마다 주석을 추가하고, 변수명 하나를 바꿀 때도 설명을 업데이트합니다. PR에 코드 변경보다 주석 추가가 더 많을 때도 있습니다. 팀원 중 빠른 실행을 원하는 HACK 유형과 마찰이 잦은 이유이기도 합니다. 그러나 장기적으로 팀의 지식 자산을 쌓는 데 없어서는 안 될 존재입니다.
"6개월 후의 내가 이 코드를 보게 될 거예요. 그때 내가 욕하지 않도록 지금 충분히 설명해두는 게 저에 대한 예의죠. 미래의 동료에게도 마찬가지고요."
— DOCS 유형 백엔드 개발자DOCS 유형이 팀에 합류한 첫 주, 그리고 6개월 후의 풍경을 비교해봅니다.
DOCS 유형이 있는 팀은 지식 자산이 빠르게 쌓입니다. 신규 팀원의 온보딩 시간이 절반으로 줄고, 담당자 부재 시에도 문서를 참고해 업무가 돌아갑니다. API 문서가 잘 되어 있어 프론트엔드-백엔드 커뮤니케이션 비용이 크게 낮아집니다. 의사결정 기록이 남아 있어 기술 부채가 생긴 이유를 추적할 수 있고, 같은 실수를 반복하지 않게 됩니다. 코드리뷰에서 논리적 근거가 명확하고, 외부 기여자가 프로젝트에 참여하기 쉬운 환경을 만듭니다.
문서가 코드보다 앞서면 실제 구현 속도가 떨어집니다. 아직 확정되지 않은 스펙을 문서로 먼저 써두었다가 요구사항이 바뀌면 문서와 코드가 따로 노는 상황이 발생하기도 합니다. 또한 모든 것을 문서화하려는 경향이 유지보수 부담으로 이어질 수 있습니다. '살아있는 문서(living documentation)' 관점으로 접근해, 코드 자체가 문서가 되도록 변수명과 함수명을 명확하게 짓는 것을 먼저 고려하는 것도 좋은 방법입니다.