문서화, 하지 마세요.

저는 문서화를 중요하게 여기지만 사실 문서는 적으면 적을수록 좋다고 생각합니다. 코드를 최소한으로 작성해 효과적으로문제를 해결하는 것이 기술이듯 문서도 최소한으로 작성하면서 필요한 정보를 전달해야 합니다.

지난 3년간 회사의 FE팀 위키를 구축하고 유지보수하며 저만의 문서화 기준이 생겼는데요. 이 글에서는 문서화가 필요한 경우와 필요하지 않은 경우를 구분하는 기준을 제시하고, 실용적인 문서화를 통해 개발 효율성을 높이는 방법을 탐색해 보겠습니다.

덮어놓고 쓰다 보면...

회사에서는 크게 3가지 방식으로 문서화를 해왔습니다.

1. 코드 주석
2. Pull Request 설명
3. 노션

그중 노션은 시간과 정성을 들여 작성해야 하는 '공식적인 문서' 역할이었는데요. 코드 설계나 구성에 대한 설명, 리팩토링 과정, 에러 핸들링 기록, PoC 상세 내용 등을 기록했습니다. 그렇게 3년 정도 노션에 열심히 문서를 쌓아놓다 보니 몇몇 불편한 부분들이 느껴졌습니다.

모든 게 중요해지면 결국 아무것도 중요하지 않게 된다

문서가 쌓이면서 검색이 어려워지고, 최신 문서와 오래된 문서가 제대로 정리되지 않아 어떤 정보가 신뢰할 만한지 파악하기도 어려웠습니다.

코드는 계속 변경되는데 문서가 그 속도를 쫓아가지 못하면 그 문서는 더 이상 유용하지 않게 됩니다. 문서도 프로젝트 코드처럼 계속 관리해주어야 하는데 그러지 않으면 어느 순간 정리에 엄두가 안 날 정도로 문서가 쌓이게 되더라고요.

영원히 끝나지 않는 문서

회사에서는 문서 작성에 할애할 시간이 부족하기도 합니다. 기능 구현할 것은 많고, 코드 리뷰도 해야 하고, 회의 준비도 해야 하고, 면접에도 들어가야 하고,... 문서 작성은 항상 우선순위가 낮아질 수밖에요.

충격. 2년째 작성 중인 문서, 실존!

어떤 문서는 영원히 완성되지 않기도 합니다.

어떤 기준으로 문서를 작성해야 할까?

📝 문서화가 필요한 경우

1. 코드와 관련 없는 정보 : 팀 소개나 회고, 회의록 등 코드와 직접적인 연관이 없는 문서는 노션이 적합합니다.
2. 최신화가 필요 없는 정보 : 기술 소개 문서처럼 한 번 작성해 놓고 동료들과 공유해야 하는 경우, 문서를 작성해 두면 좋습니다. 기술 결정 사항(당시 기술을 선택한 이유, 장단점, 논의 사항) 같은 정보도 코드 주석에 구구절절 설명하기에는 길어지는 경향이 있기 때문에 github의 issue나 discussion 기능을 활용해 기록해 놓고 코드 주석에 url만 첨부하는 방식도 좋았습니다.
3. 비정기적이지만 반복되는 업무 : 개발환경 세팅방법 같은 경우, 정기적으로 하는 업무는 아니지만 가끔씩 할 때 참고할 수 있는 문서가 있으면 좋습니다.
4. 코드만으로 전달이 어려운 개념 : 도메인 지식이나 제품의 특성에 대한 설명, 까다롭게 구현된 코드의 비하인드 등 코드만으로 이해하기 어려운 정보는 문서화가 필요합니다.

문서를 작성하기 전에 문서화가 필요한 정보인지 아닌지 파악이 어렵다면 인수인계 관점으로 생각해 보세요!

• 신규 입사자가 들어왔을 때, 이 문서를 보고 업무를 진행할 수 있을까?

• 내가 팀에 없을 때 코드만 보고 다른 사람이 문맥을 파악할 수 있을까?

• 이 문서는 내가 아니어도 유지보수가 가능한가?

🗑️ 문서화가 필요하지 않은 경우

1. 자주 바뀌는 정보 : 코드 구성, UI 세부사항 등에 대한 정보는 굳이 노션으로 작성할 필요가 없습니다. 코드가 변경될 때마다 문서도 함께 변경해 줄 것이 아니라면 작성하지 않거나, 가능한 코드와 가까운 곳(ex. 주석)에 정보를 기록하세요. 이런 정보에 대해 문서화가 필요하다면 자동화가 가능한지를 우선적으로 살펴보는 것이 좋습니다. API 문서는 Swagger, ReDoc과 같은 도구를 활용해 자동 생성하면 코드 변경을 즉각적으로 반영할 수 있어 문서의 신뢰도를 높여줍니다.
2. 자동화 도구를 활용할 수 있는 경우 : 컨벤션은 문서로 서술하는 것보다 Prettier, ESLint 같은 도구를 활용해 강제하는 것이 더 효과적입니다. 코드를 작성할 때마다 매번 컨벤션 문서를 참조하지 않아도 되고, 도구를 적용하면 휴먼 에러가 줄어들기 때문입니다. 규칙을 정할 때에도 자동화할 수 있는지 고려해 보세요.
3. 코드로 전달할 수 있는 정보 : 함수명이나 변수명이 충분히 명시적이어서 코드만으로도 의도를 전달할 수 있다면 문서화하지 않습니다.

사실 대부분의 문서는 필요 없다고 생각합니다. 유지보수를 제대로 하지 못해 잘못된 정보를 담고 있거나 애초에 완성되지 못한 문서는 있느니만 못하거든요.

문서만큼은 미니멀리즘!

문서는 개발을 거들 뿐, 문서를 위한 문서를 만드는 것은 피해야합니다.

• 필요없는 문서는 삭제하고
• 문서의 목적과 예상 독자를 생각하고
• 가능하면 코드 변경을 즉각 반영할 수 있도록 하고 (자동화 할 수 있다면 자동화)
• 정기적으로 유지보수 하고
• 가능하면 코드만으로 의도를 명확히 전달할 수 있도록 노력합시다.

이제는 '문서화 언젠가는 꼭 해야하는데...'라는 부채감에서 벗어나 '필요한 문서만 최소한으로 유지'하는 방향으로 전환할 때입니다. 문서는 많을수록 좋은 것이 아니라, 필요한 만큼, 정확한 정보를 담고 있을 때 가치가 있습니다.