개발자가 문서 작성도 잘해야 했어요

개발자가 문서 작성도 잘해야 하나요? - 글쓰기의 기본은 물론, AI와 함께 쓰는 법까지!
나카타 나오히로 지음, 김정민 옮김 / 길벗 / 2026년 8월

그동안 글쓰기가 기술 블로그의 출발점이 되고, 개발자의 생각을 정리하고, 질문하는 힘을 길러준다는 점을 직접 경험했어요.

개발자가 글을 쓸 일은 생각보다 많습니다. 코드뿐 아니라 커밋 메시지, PR, 코드 리뷰, 기능 명세서와 업무 문서도 다른 사람에게 생각을 전달하는 글입니다. 저는 이 점을 매일 글을 쓰며 조금씩 알아갔었어요.

그래서 『개발자가 문서 작성도 잘해야 하나요?』라는 제목은 제게 낯선 질문이 아니었습니다. 오히려 궁금했어요.

내가 그동안 글쓰기를 하며 어렴풋이 느껴왔던 것을 저자는 어떻게 정제해서 풀어냈을지 알고 싶었죠.

책을 읽으며 놀랐던 건, 제가 해오던 생각과 이 책의 관점이 많이 맞닿아 있었다는 점입니다. 제가 경험적으로 익힌 것을 더 정제되고, 근거와 논리를 갖춘 개념으로 만나는 과정이 무척 재미있었습니다.

문서 작성은 문장보다 먼저 설계하는 일

이 책은 글을 잘 쓰는 요령부터 이야기하기보다, 문서를 왜 쓰는지와 누가 읽을지를 먼저 생각하게 합니다.

공개 목차를 따라가면 문서의 목적을 설명형·보고형·설득형으로 나누고, 독자와 주제를 정한 뒤 내용을 세분화해 아웃라인을 만듭니다. 그다음 문단과 문장을 구성하고, 요구사항 정의서나 기능 명세서 같은 실무 문서에 적용합니다.

이 흐름에서 제가 특히 흥미롭게 본 것은 글쓰기와 프로그래밍을 연결하는 관점이었습니다.

프로그램을 만들 때 요구사항과 구조를 정리한 다음 코드를 작성하듯, 문서도 첫 문장부터 쓰기보다 독자와 주제를 정하고 구조를 설계한다는 거예요. 글쓰기와 프로그래밍 모두 처음의 설계가 뒤의 작업을 크게 좌우한다는 설명은 제가 글을 쓰며 느꼈던 점과 잘 맞았습니다.

매일 짧은 글을 쓸 때도 저는 소재를 정하고, 어떤 일이 있었는지 돌아보고, 그 경험에서 무엇을 느꼈는지 정리해야 했습니다. 글을 쓰려면 생각 정리가 먼저 필요했어요. 개발 구현 전에 요구사항을 분석하고 우선순위를 정하는 과정과 닮아 있었습니다.

저는 이 책에서 제가 해오던 방식을 새로 배운다기보다, 왜 그 방식이 글을 쓰고 전달하는 데 도움이 됐는지를 더 명확한 언어로 이해하는 재미를 느꼈습니다.

누구에게 무엇을 전할지 정하면 문서의 모양도 달라진다

같은 내용도 누가 읽느냐에 따라 전달 방식이 달라집니다. 개발자가 볼 기능 명세서, 사용자가 볼 매뉴얼, 진행 상황을 공유하는 보고서는 목적도 읽는 방식도 같지 않습니다.

이 책은 독자와 주제를 좁히고, ‘왜·무엇을·어떻게’로 내용을 나누며, 필요한 정보를 어떤 순서로 보여줄지 구성하도록 안내합니다. 결국 문서의 구조를 정하는 일은 읽는 사람이 내용을 이해하고 필요한 정보를 찾아가도록 돕는 일과 이어집니다.

이 점은 제가 글쓰기와 개발 문서를 바라봐온 태도와도 맞닿아 있습니다. 공개 글을 쓸 때는 내 생각을 표현하는 데서 멈출 수 없었습니다. 읽는 사람이 어디에서 들어오고 무엇을 알아야 할지 생각해야 했어요. 개발 문서와 PR에서도 마찬가지였습니다. 내가 아는 내용을 적는 것과 상대가 이해할 수 있게 설명하는 것은 다른 일이니까요.

초기 글쓰기 현황판에 적어둔 원칙도 떠올랐습니다. 책 내용을 그대로 옮기기보다 책 3, 내 생각 7의 비율로 쓰고, 실제 일상에서 겪은 경험과 단상을 담자는 것이었어요. 책에서 얻은 생각을 내 경험과 연결해 다시 설명하려 했던 태도가 이 책의 구조적 접근과 잘 어울렸습니다.

챗GPT는 대신 쓰는 사람이 아니라 함께 다듬는 도구

책 후반부는 챗GPT로 문서의 구성과 초안을 만들고, 문장을 교정하는 방법을 다룹니다. 동시에 챗GPT에 모든 것을 맡기기보다 도움을 받는 도구로 활용한다는 방향도 제시합니다.

저도 AI와 대화하며 생각이 더 깊어진 경험이 있습니다. 질문을 입력하려다 상황을 정리하는 과정에서 스스로 답을 찾기도 했어요. AI가 글의 구조를 제안하거나 초안을 만드는 데 도움을 줄 수 있지만, 어떤 맥락을 담아야 하는지와 실제 내용이 맞는지까지 저절로 판단해주지는 않습니다.

문서를 작성하는 사람이 자신의 경험과 목적을 먼저 정리하고, AI가 만든 결과를 확인하고 고치는 과정이 필요합니다. AI가 문장을 만들어주는 속도와 사람이 책임져야 하는 판단은 구분해야 하니까요.

그래서 AI 활용 장도 제게는 글쓰기를 AI에게 넘기는 방법보다, 내 생각과 정보를 더 잘 정리하기 위해 AI를 어디에 참여시킬지 생각하는 부분으로 다가왔습니다.

글쓰기를 해온 사람에게도 새롭게 읽히는 이유

이 책의 내용은 독자와 주제를 정하고, 문서 구조를 만들고, 문단과 문장을 다듬는 과정으로 이어집니다. 마지막에는 요구사항 정의서, 기능 명세서, 사용자 매뉴얼, 보고서의 구성 예시를 다룹니다.

저는 개발자 글쓰기를 이미 중요하게 여겨왔습니다. 그러면서도 내가 알고 있는 내용을 다른 사람이 이해할 수 있게 쓰는 일은 매번 생각과 설계를 필요로 한다는 점도 경험했어요. 이 책이 재미있었던 이유는 글쓰기의 중요성을 다시 주장해서가 아니라, 제가 경험으로 붙잡아온 생각을 더 정제된 구조로 설명해주었기 때문입니다.

책을 읽는 동안 제 글쓰기 경험과 저자의 관점이 계속 겹쳐 보였습니다. 감각적으로 알고 있던 것에 개념과 근거가 붙으니, “내가 이래서 글을 쓰고 있었구나”를 더 선명하게 이해할 수 있었습니다.

마치며

짧은 글쓰기는 제게 경험과 생각을 밖으로 꺼내고 정리하는 연습이자 실전이었어요. 이 책은 그 생각을 독자와 목적에 맞게 구조화해 문서로 만드는 과정을 보여주었습니다.

글쓰기를 처음 시작하려는 개발자에게는 어디서부터 시작할지 알려주는 안내가 될 수 있고, 이미 문서를 써온 개발자에게는 자신의 방식을 다시 살펴보고 정리하는 계기가 될 수 있습니다. 특히 글쓰기의 필요성을 이미 알고 실천해온 사람이라면, 경험으로 익힌 감각을 개념과 구조로 다시 만나는 재미가 있을 거예요.

지금은 육아를 하다보니 글쓰기를 매일 같이 하고 있지는 못하지만, 그동안 쌓은 경험이 사라지진 않은 것 같아요. 다시 글을 쓰고 개발 문서나 PR을 작성할 때, 누구에게 무엇을 어떤 순서로 전할지 한 번 더 생각해보고 싶습니다. 이 책은 제가 해오던 글쓰기를 낯설게 바꾸기보다, 그 안에 있던 생각을 더 잘 보이게 해준 책이었습니다.