출판사로부터 도서를 제공받아 주관적으로 작성한 리뷰입니다.

협업을 위해서는 개발자 역시 SWAGGER, 요구사항 정의서, 위키 등 수많은 문서를 다뤄야만 합니다. 그동안 어떤 문서가 좋은 문서인지 감을 잡기 어려웠다면, 이 책을 통해 단락 단위로 글의 뼈대를 잡는 법을 확실히 배울 수 있습니다. 특히 하나의 단락에 하나의 화제만 담는 '단일 책임 원칙'은 실무에 즉시 적용하기 좋은 가이드였습니다. 명확한 기획 문서 없이 AI에게 무작정 코딩을 맡기면 결국 로직이 꼬이고 프로젝트가 무너집니다. 책에 수록된 실무 템플릿과 AI 프롬프트 작성법을 참고한다면, 소통 비용을 줄이는 것은 물론 AI를 제대로 부리는 능력까지 기를 수 있을 것입니다. 협업 능률을 높이고 싶은 모든 개발자에게 권합니다.

AI가 코드와 글을 빠르게 만들어주는 시대일수록 요구사항과 기능을 정확하게 구조화하고 설명하는 능력이 더 중요하다고 느꼈습니다. 요구사항 정의서, 기능 명세서, 사용자 매뉴얼, 보고서까지 실제 개발 과정에서 자주 쓰는 문서 예시가 잘 정리되어 있어 바이브 코딩이나 AI 기반 개발을 하는 사람에게도 실용적인 책입니다.

이 책을 읽기 전부터 개발자에게 문서 작성 능력이 중요하다는 사실은 알고 있었다. 사실 알 수밖에 없었다. 회사에서 문서를 작성하면서 몇 번 피드백을 받은 경험이 있었기 때문이다. 특히 문서를 너무 작성자 중심으로 쓴다는 이야기를 들었던 것이 기억에 남는다.

문서가 중요하다는 사실은 알았지만, 읽는 사람을 고려해서 문서를 쓴다는 것은 생각보다 어려웠다. 특히 코드나 데이터를 다룬 내용을 문서로 옮길 때 더 그랬다. 내가 이미 알고 있는 내용은 어느 순간부터 머릿속에서 ‘당연한 것’이 되었고, 그 때문에 다른 사람이 읽을 때 필요한 설명을 자연스럽게 생략하기도 했다.

혼자 작업하는 데 익숙했던 것도 영향을 주었던 것 같다. 입사 이후 혼자 진행하는 작업이 많았고, GitHub에 코드를 올리는 것도 문서를 작성하는 것도 결국 내가 만들고 내가 다시 읽는 경우가 많았다. 내가 읽는 문서라면 중간에 빠진 맥락을 스스로 채울 수 있지만, 다른 사람이 읽는 문서는 그렇지 않다는 점을 제대로 체감하기까지 시간이 필요했다.

이 책을 읽으면서 가장 도움이 되었던 부분은 글을 잘 쓰는 방법 이전에 문서의 구조를 만드는 과정을 구체적으로 설명한다는 점이었다.

독자와 주제를 선정하고, 주제를 나누고, 아웃라인과 개요를 만든 뒤 실제 문장으로 옮기는 과정을 먼저 전체적으로 소개하고 이후 각 단계를 깊게 설명한다. 특히 아웃라인을 만들면서 ‘왜, 무엇을, 어떻게’를 각각의 구성 요소로 활용해 내용을 구조화하는 방식이 인상적이었다.

막연히 ‘독자를 고려해서 쓰자’고 생각하는 것보다, 내가 전달하려는 정보가 왜 필요한지, 무엇을 전달해야 하는지, 그것을 어떻게 설명할 것인지를 구분해보는 것만으로도 문서의 방향이 훨씬 명확해질 수 있겠다는 생각이 들었다.

실제 업무에서 작성했던 보고서들도 자연스럽게 돌아보게 됐다. 기술적인 용어를 완전히 풀어 설명하기 어려울 때가 많아, 나는 주요 용어의 의미와 결론을 서론에 먼저 배치하는 방식을 자주 사용했다. 그런데 책에서 사람들이 문서를 처음부터 끝까지 정독하기보다 필요한 부분을 빠르게 훑어보는 경우가 많다는 내용을 접하면서 한 가지 생각이 들었다.

내가 중요하다고 생각해서 앞에 적어둔 용어들이 과연 독자에게도 중요한 정보였을까?

차라리 해당 내용이 필요한 위치에서 구성 요소로 설명하거나, 독자가 굳이 알 필요가 없는 내용이라면 과감하게 줄이는 것이 더 좋은 문서일 수도 있다. 독자를 고려한다는 것은 어려운 내용을 모두 쉽게 풀어 쓰는 것뿐 아니라, 독자가 무엇을 알아야 하고 무엇은 몰라도 되는지를 선택하는 과정일 수도 있다는 점이 기억에 남았다.

문장과 패러그래프를 만드는 방법도 도움이 됐다. 핵심 문장을 먼저 제시하고, 왜 그렇게 이야기하는지 이유를 설명한 뒤 내용을 풀어내고 구체적인 사례를 덧붙이는 방식이다. 이런 구조를 활용하면 생각나는 내용을 두서없이 이어 쓰는 습관도 어느 정도 줄일 수 있을 것 같았다.

일반적인 작법서와 달리 업무용 글쓰기에 초점을 맞추고 있다는 점도 좋았다. 실제 회사 생활에서 여러 번 문서를 쓰고 피드백을 받으며 경험으로 익힐 법한 내용을 하나씩 명확한 방법으로 배운다는 느낌이 컸다.

생성형 AI를 활용한 글쓰기 부분도 흥미로웠다. AI에게 처음부터 완성된 문서를 만들어달라고 요청하는 것이 아니라, 아웃라인을 함께 구성하고 초안을 만든 뒤 평가와 리뷰를 반복하는 방식으로 활용한다. 특히 API 명세서와 같은 개발 실무 문서를 직접 작성하는 예제가 포함되어 있어 실제 업무에 어떻게 적용할지 떠올려보기 쉬웠다.

이 책을 읽고 나서 문서를 바라보는 기준이 조금 달라졌다. 이전에는 내가 알고 있는 내용을 빠짐없이 전달하는 것이 중요하다고 생각했다면, 이제는 이 문서를 읽는 사람이 무엇을 알고 싶어 하는지, 어떤 순서로 정보를 받아야 이해하기 쉬운지를 먼저 생각해야 한다는 쪽으로 시선이 옮겨갔다.

개발자에게 문서 작성은 코드와 별개의 부가 업무가 아니라, 자신이 만든 것을 다른 사람과 공유하고 협업하기 위한 또 하나의 개발 능력일지도 모른다.

문서의 중요성은 알고 있지만 어떻게 써야 할지 막막했던 개발자, 특히 기술적인 내용을 다른 사람에게 설명하는 데 어려움을 느껴본 개발자라면 한 번 읽어볼 만한 책이라고 생각한다.

#협찬 

#협찬

개발자를 위한 글쓰기 책이지만, 문서 작성이 필요한 사람이라면 누구나 읽어볼 만한 책입니다.

이 책은 단순히 글을 쓰는 방법만 설명하지 않습니다. 독자를 이해하고, 주제를 정하고, 문서 구조를 설계하는 과정까지 다룹니다. 본격적인 글쓰기 내용은 후반부에 나오지만, 오히려 그 전에 설명하는 준비 과정이 인상적이었습니다.

분량이 300페이지가 채 되지 않아 부담 없이 읽을 수 있고, 일러스트와 예시가 적절히 들어가 있어 이해하기도 쉽습니다. 개발자뿐 아니라 기술 문서, 보고서, 매뉴얼 등 체계적인 문서 작성이 필요한 사람에게 추천하고 싶은 책입니다.