Docs for Developers - 후기

moseoh

저는 개발자로 일하면서 문서 작성에 대해 꽤 많이 고민했습니다. 독자를 위해 글을 쓴다는 것, 문서를 체계적으로 구조화한다는 것에 대해 나름 깊이 생각하며 작성해왔거든요. 그런데 이 책을 읽으면서 아, 내가 놓치고 있던 부분이 있었구나 싶었습니다.

‘Docs for Developers’는 제가 막연하게 생각했던 것들을 명확하게 정리해줬어요. 특히 독자 페르소나를 구체적으로 설정하고, 그에 따라 문서 작성 프로세스를 체계화하는 방법은 이 책을 통해 처음 접했습니다. 그동안 독자를 생각한다는 건 알았지만, 페르소나로 구체화하고 그걸 기반으로 전체 프로세스를 설계한다는 건 미처 생각하지 못했던 부분이었거든요. 그간 정리되어있지 않던 저의 문서 작성법이 하나의 프레임워크로 정리되는 느낌이었어요.

특히 인상 깊었던 부분들

다양한 문서를 읽다 보면 어떤 문서는 쉽게 읽히는 반면, 어떤 문서는 아무리 시간을 들여도 진전이 없는 경우가 있었어요. 능력 좋은 사람들이 쓴 글일 텐데 내가 이해를 못하는 건가 싶었을 때가 많았습니다. 그런데 이 책에서 문서 품질을 기능적 품질과 구조적 품질로 나누어 평가하는 관점을 보면서, 아, 문서 자체에도 명확한 품질 기준이 있었구나 싶었습니다. 특히 접근성 부분에서 고등학교 1~2학년이 이해할 수 있는 수준이라는 구체적인 기준을 제시한 게 인상적이었어요. 막연히 쉽게 써야지 하던 걸 명확한 기준으로 만들어준 셈이죠.

실무에 적용할 계획

이 책을 읽고 나서 당장 해보고 싶은 게 몇 가지 생겼어요. 우선 문서 템플릿을 체계적으로 만들어 팀에서 활용해보려고 합니다. README, How-to 가이드, 트러블슈팅 문서처럼 자주 쓰는 유형별로 템플릿을 준비해두면 문서 작성의 부담이 훨씬 줄어들 것 같거든요.

그리고 문서 유지보수를 자동화하는 것도 시도해볼 생각이에요. 6개월마다 문서 유효성을 확인하는 알람 시스템은 간단하면서도 효과적인 아이디어더라고요. 특히 빠르게 변화하는 프로젝트에서는 필수적일 것 같습니다.

샘플 코드를 작성할 때 변수명에 대한 이야기도 인상적이었어요. 처음에는 your_password처럼 의미 있는 이름을 쓰다가, 다른 문서들에서 foo, bar 같은 걸 보고 따라 썼거든요. 뭔가 있어 보이고있어빌리티 전문적인 느낌이 들어서요. 그런데 이 책을 읽으면서 내가 원래 하던 방식이 더 나았다는 걸 알게 됐습니다. 사소해 보이지만 독자의 이해도를 크게 높일 수 있는 디테일이더라고요.

마치며

Docs for Developers는 문서 작성에 관심이 있는 개발자라면 한 번쯤 읽어볼 만한 책이에요. 이미 알고 있는 내용이 많더라도, 그 지식을 체계적으로 정리하고 구체적인 실천 방안을 제시한다는 점에서 충분한 가치가 있습니다.

이 책이 다루는 문서 작성 요령은 사실 개발 Docs에만 국한되지 않아요. 업무를 하면서 상사에게 보고하거나 동료들에게 정보를 전파할 때도 결국 문서로 소통하게 되잖아요. 독자를 고려하고, 구조를 명확히 하고, 핵심을 잘 전달하는 능력은 개발자로서뿐만 아니라 조직 구성원으로서도 정말 중요한 역량이라고 생각합니다.

그리고 요즘 들어 문서 작성이 더욱 중요해진 이유 중 하나는 AI 라고 생각합니다. 사람만 읽는 게 아니라 이제는 AI agent도 문서를 읽고 작업하는 시대가 됐거든요. 실제로 문서를 잘 작성해두면 AI Agent가 더 잘 작업하고 있었습니다. 구조화된 문서, 명확한 설명, 구체적인 예시가 있으면 AI가 훨씬 정확하게 이해하고 도움을 줍니다. 이런 부분까지 고려하면서 문서를 작성하는 게 이제는 필수가 된 것 같아요.

무엇보다 목적을 달성하는 문서가 좋은 문서다라는 핵심 메시지가 마음에 남네요. 화려한 문서가 아니라 독자에게 실질적인 도움을 주는 문서, 그게 우리가 추구해야 할 방향이 아닐까 싶습니다.

앞으로도 계속해서 더 나은 문서를 작성하기 위해 노력하겠습니다. 이 책이 그 여정에 좋은 이정표가 되어준 것 같아 감사한 마음이에요.