문서화는 개발자의 운영 능력입니다
개발을 하다 보면 문서화는 늘 뒤로 밀립니다.
기능을 먼저 만들어야 하고, 장애를 먼저 봐야 하고, 배포 일정을 맞춰야 합니다. 그래서 문서는 시간이 남으면 하는 일처럼 취급되기 쉽습니다.
하지만 프로젝트를 오래 운영하다 보면 문서화는 개발과 분리된 일이 아니라는 것을 알게 됩니다. 문서는 코드를 설명하는 부수적인 산출물이 아니라, 다음 개발자가 시스템을 안전하게 다루기 위한 운영 지식입니다.
문서가 없으면 코드는 느리게 읽힙니다
소스 코드는 가장 정확한 정보입니다. 실제로 실행되는 것은 문서가 아니라 코드이기 때문입니다.
그런데 소스 코드만으로는 처음 보는 사람이 빠르게 판단하기 어렵습니다. 비즈니스는 어떻게 흐르고 있고, 데이터는 어떻게 쌓여가고 있으며, 어떤 설정이 운영에 영향을 주는지, 어떤 API가 외부 진입점인지, 어떤 계약 파일을 수정해야 하는지, 어떤 모듈이 어떤 역할을 맡는지는 코드 곳곳에 흩어져 있습니다.
숙련된 개발자는 결국 찾아냅니다. 하지만 매번 찾아내야 한다면 그 시간은 모두 비용입니다.
문서화의 첫 번째 목적은 이 비용을 줄이는 것입니다.
소스 기준 문서 화가 재미가 없지만 필요한 이유
좋은 기술 문서는 희망사항을 적지 않습니다. 배경에 대한 설명보다는 현재 소스가 어떻게 동작하는지, 어떤 설정이 실제로 읽히는지, 어떤 API가 공개되어 있는지, 어떤 파일을 수정하면 런타임에 반영되는지를 기준으로 작성되기 때문입니다.
특히 HandStack처럼 모듈, 계약, 거래 라우팅, 화면 라이브러리가 함께 움직이는 구조에서는 문서가 추상적인 설명에 머물면 실무에 도움이 되기 어렵습니다.
개발자가 알고 싶은 것은 보통 단순합니다.
- 이 모듈은 무엇을 책임지는가?
- 외부에서 들어오는 API는 무엇인가?
- 계약 파일은 어디에 두는가?
- 설정을 바꾸면 어떤 실행 흐름이 달라지는가?
- 장애가 나면 어디부터 봐야 하는가?
이 질문에 답하지 못하는 문서는 읽기 좋은 글일 수는 있어도, 실무 문서로는 부족합니다. 그래서 문서화는 만드는 것도 읽는 것도 재미가 없을 수 있지만, 다음 개발자와 운영자가 시스템을 안전하게 다루도록 돕는 가장 확실한 방법입니다.