저는 문서화를 중요하게 여기지만 사실 문서는 적으면 적을수록 좋다고 생각합니다. 코드를 최소한으로 작성해 효과적으로문제를 해결하는 것이 기술이듯 문서도 최소한으로 작성하면서 필요한 정보를 전달해야 합니다.
지난 3년간 회사의 FE팀 위키를 구축하고 유지보수하며 저만의 문서화 기준이 생겼는데요. 이 글에서는 문서화가 필요한 경우와 필요하지 않은 경우를 구분하는 기준을 제시하고, 실용적인 문서화를 통해 개발 효율성을 높이는 방법을 탐색해 보겠습니다.
회사에서는 크게 3가지 방식으로 문서화를 해왔습니다.
그중 노션은 시간과 정성을 들여 작성해야 하는 '공식적인 문서' 역할이었는데요. 코드 설계나 구성에 대한 설명, 리팩토링 과정, 에러 핸들링 기록, PoC 상세 내용 등을 기록했습니다. 그렇게 3년 정도 노션에 열심히 문서를 쌓아놓다 보니 몇몇 불편한 부분들이 느껴졌습니다.
아이유의 노래 '첫 이별 그날 밤'을 듣다가 '처음'에 대해 생각하게 되었습니다. 입사 후 저의 첫 커밋, 첫 PR(Pull Request)이 생각났어요. 처음 PR을 작성하고, approve를 받아 메인 코드 베이스에 머지했던 그날은 드디어 사회에서 1인분을 하는 사람이 되어간다는 기분에 설레는 마음이 가득했던 것 같습니다.
입사 후 첫 3주동안에는 회사 제품을 사용해보고, 제품 코드를 리딩하는 업무를 진행했습니다. 약 3년정도 진행중인 프로젝트여서 코드 베이스가 크고 복잡했는데요. 가장 먼저 눈에 들어온 부분은 코드 컨벤션이었습니다.
가장 처음 작업했던 것은 커밋 메시지를 자동화하고, PR 템플릿을 만든 일이었습니다. 프로젝트를 빠르게 개발하는 것이 가장 중요했던 시기라서 제가 입사하기 전에는 문서화 작업이 많이 부족했는데요. 코드 리뷰를 구두로 진행하고, PR에 관련 작업에 대한 설명이 대부분 없었습니다.
예를들면 이런식...
약 2,000 라인이 넘는 changes임에도 불구하고, PR에 아무런 설명이 없었어요. 3년간의 히스토리를 아무런 기록 없이 넘겨받으려니 엄청 막막했습니다. 그래서 PR에 대한 템플릿을 만들어 최소한으로 남겨놓아야할 정보들을 기록할 수 있도록 만들었어요.
역사적인 첫 PR🥳