문서화는 개발자의 운영 능력입니다

개발을 하다 보면 문서화는 늘 뒤로 밀립니다.

기능을 먼저 만들어야 하고, 장애를 먼저 봐야 하고, 배포 일정을 맞춰야 합니다. 그래서 문서는 시간이 남으면 하는 일처럼 취급되기 쉽습니다.

하지만 프로젝트를 오래 운영하다 보면 문서화는 개발과 분리된 일이 아니라는 것을 알게 됩니다. 문서는 코드를 설명하는 부수적인 산출물이 아니라, 다음 개발자가 시스템을 안전하게 다루기 위한 운영 지식입니다.

문서가 없으면 코드는 느리게 읽힙니다

소스 코드는 가장 정확한 정보입니다. 실제로 실행되는 것은 문서가 아니라 코드이기 때문입니다.

그런데 소스 코드만으로는 처음 보는 사람이 빠르게 판단하기 어렵습니다. 비즈니스는 어떻게 흐르고 있고, 데이터는 어떻게 쌓여가고 있으며, 어떤 설정이 운영에 영향을 주는지, 어떤 API가 외부 진입점인지, 어떤 계약 파일을 수정해야 하는지, 어떤 모듈이 어떤 역할을 맡는지는 코드 곳곳에 흩어져 있습니다.

숙련된 개발자는 결국 찾아냅니다. 하지만 매번 찾아내야 한다면 그 시간은 모두 비용입니다.

문서화의 첫 번째 목적은 이 비용을 줄이는 것입니다.

소스 기준 문서화가 재미가 없지만 필요한 이유

좋은 기술 문서는 희망사항을 적지 않습니다. 배경에 대한 설명보다는 현재 소스가 어떻게 동작하는지, 어떤 설정이 실제로 읽히는지, 어떤 API가 공개되어 있는지, 어떤 파일을 수정하면 런타임에 반영되는지를 기준으로 작성되기 때문입니다.

특히 HandStack처럼 모듈, 계약, 거래 라우팅, 화면 라이브러리가 함께 움직이는 구조에서는 문서가 추상적인 설명에 머물면 실무에 도움이 되기 어렵습니다.

개발자가 알고 싶은 것은 보통 단순합니다.

• 이 모듈은 무엇을 책임지는가?
• 외부에서 들어오는 API는 무엇인가?
• 계약 파일은 어디에 두는가?
• 설정을 바꾸면 어떤 실행 흐름이 달라지는가?
• 장애가 나면 어디부터 봐야 하는가?

이 질문에 답하지 못하는 문서는 읽기 좋은 글일 수는 있어도, 실무 문서로는 부족합니다. 그래서 문서화는 만드는 것도 읽는 것도 재미가 없을 수 있지만, 다음 개발자와 운영자가 시스템을 안전하게 다루도록 돕는 가장 확실한 방법입니다.

좋은 문서는 질문을 줄이는 문서입니다

물론 질문이 사라지는 것은 아닙니다. 좋은 질문은 언제나 필요합니다. 하지만 반복되는 질문, 같은 실수를 유발하는 질문, 시스템 구조를 몰라서 생기는 질문은 문서를 잘 쓰면 줄일 수 있습니다.

신규 개발자가 프로젝트에 들어왔을 때 가장 먼저 필요한 것은 완벽한 이해가 아닙니다. 어디부터 보면 되는지 아는 것입니다.

운영자가 장애를 만났을 때 가장 먼저 필요한 것도 모든 코드의 이해가 아닙니다. 어떤 설정과 로그와 계약을 확인해야 하는지 아는 것입니다.

HandStack 문서는 이 첫 방향을 잡아주는 역할을 하려고 노력합니다. 개발자는 코드를 작성하는 사람인 동시에, 그 코드가 오래 운영될 수 있도록 맥락을 남기는 사람입니다.

오늘 작성한 문서가 내일 누군가의 시간을 줄여준다면, 그것은 충분히 가치 있는 개발입니다.