문서는 실력이고, 글은 또 하나의 코드입니다

 

개발자는 오늘도 글을 씁니다. 커밋 메시지부터 리드미, 릴리스 노트, 기술 블로그까지 일의 많은 순간에 글이 필요합니다. 이 책은 그런 글을 더 잘 쓰고 싶은 개발자를 위한 실전 가이드입니다. 주석, 예제 코드, 시작하기 문서처럼 자주 마주치는 글쓰기부터 정확하고 간결한 기술 문서 작성법, 이메일과 메시지, ChatGPT 활용 팁까지 실무에 꼭 맞는 내용으로 구성했습니다. 글이 쌓이면 문서가 되고 문서는 곧 실력이 됩니다. 글 앞에서 자주 멈칫하는 개발자에게 이 책이 글쓰기 실력을 키우는 든든한 첫걸음이 되어줄 것입니다.

[목 차]

추천의 글 12

베타리더 후기 18

여는 글 20

 

PART I 개발자는 정말 글을 못 쓸까?

1 개발자는 코드로 소통한다? 27

2 반복, 또 반복 29

3 글에는 목적이 있다 31

4 번역서 참고는 그만 34

 

PART II 글을 잘 쓰는 개발자는 코드부터 다르다

5 커밋 메시지 작성하기 41

커밋 메시지를 잘 써야 하는 이유 43

커밋을 설계하세요 46

[쉬어가기] 커밋 메시지 해부학 47

커밋 메시지 제목 쓰기 49

커밋 메시지 본문 쓰기 64

커밋 메시지 작성해보기 68

커밋 메시지 맛집 70

 

6 개발자는 작명가 72

함수에 걸맞은 이름 짓기 74

함수 이름 짓기 연습 84

 

7 오류 메시지 쓰기 100

오류 메시지 구성 요소 101

오류 메시지를 봤는데 무슨 말인지 모르겠다 103

어떻게 해결해야 하는지 모르겠다 107

오류 메시지에 있는 안내대로 했는데 해결이 안 된다 109

해결 방법을 어디서 찾아야 하는지 모르겠다 109

[쉬어가기] 금과 은 나 없어도 내게 있는 것 네게 주니 110

 

8 API 주석 111

API 주석 형식 116

API 설명 기본 규칙 118

실전 연습 124

설명문 형식 정하기 128

[쉬어가기] API 설명은 영어여야만 할까요? 130

OpenAPI 명세로 쓰기 131

도구를 너무 믿지 말자 133

[쉬어가기] 미래의 나를 위해서라도 꼭 쓰세요! 134

 

PART III 개발자의 글은 곧 PR이다

9 리드미 139

나를 읽어주세요 142

리드미에 써야 할 정보는? 143

실전 리드미 작성 148

[쉬어가기] ‘모두가 아는 정보’ 판단법 153

이왕이면 다홍치마 154

템플릿, 널 위해 준비했어 157

 

10 예시 코드 159

예시 코드가 있어야 할 곳 160

소스 코드 말고 예시를 161

소스 코드를 예시로 만드는 주문 168

[쉬어가기] 예시 코드에서 내부 정보 감추기 172

샘플 프로그램 173

[쉬어가기] cURL 예시도 REST API 예시 코드일까요? 175

작동하지 않으면 코드가 아니다 177

 

11 장애 보고서 179

[쉬어가기] 서비스가 멈추는 순간, 우리가 겪는 불편함 181

장애 보고서란? 181

장애 보고서엔 무엇을 쓰나요? 183

장애 보고서는 누가 쓰나요? 192

장애 보고서는 언제 쓰나요? 193

장애 보고서는 어디에 쓰나요? 195

 

12 릴리스 노트 206

릴리스 노트? 체인지 로그? 207

[쉬어가기] 반박 시 당신 말씀이 맞습니다만, 저도 맞을 수 있지 않을까요? 210

릴리스 노트를 알아봅시다 211

[쉬어가기] 끝날 때까진 끝난 것이 아니다! deprecated는 ‘아직’이에요 213

[쉬어가기] 릴리스 노트가 길어지면 어쩌죠? 221

[쉬어가기] 문서도 릴리스 노트를 써야 할까요? 228

체인지 로그를 알아봅시다 229

[쉬어가기] 해당하는 정보가 없을 땐 없다고 명시하세요 234

 

13 시작하기 문서 236

시작하기의 도입부: 가입과 설치 238

시작하기의 핵심: 기본 기능 수행 240

시작하기의 마무리 243

문제점 찾기 연습 246

 

14 기술 블로그 253

무엇을 얻고 싶은가요? 254

블로그, 기본 틀 257

블로그, 어떤 글을 쓸까요? 268

[쉬어가기] 글로 영업해보세요 270

블로그, 쓸 때 생각해볼 것 276

[쉬어가기] 소화할 수 있는 글쓰기 277

블로그, 시작해봅시다 283

블로그, 어렵죠? 289

 

PART IV 기술 글쓰기에는 기법이 있다

15 정확성 295

정확한 용어 사용하기 298

[쉬어가기] 실무에서 쓰는 표현 기술 문서에 알맞게 포장하기 305

명령문과 평서문 307

명령문과 평서문 둘 다 표현할 수 있을 때는? 316

[쉬어가기] 쉴 수 있을 때 쉬어야 하니 쉬세요! 317

최신 정보 반영하기 317

 

16 간결성 326

두괄식으로 쓰기 328

목록과 표 335

[쉬어가기] 점 목록만으로 쓴 문서는 정말 읽기 쉬울까요? 341

[쉬어가기] 귀찮지만 포기할 수 없는 셀 병합 345

다이어그램 348

 

17 완결성 363

도입부 쓰기 364

[쉬어가기] 용어 설명은 짧은 팝업으로 출력해보세요 371

[쉬어가기] 형식과 기법보다는 내용과 목적이 중요합니다 374

일단 쓰고 지우기 374

우리말로 글쓰기 387

[쉬어가기] 지금 무슨 말을 하고 있는지 아나요? 389

[쉬어가기] 우리말, 우리글로도 할 수 있어요 396

 

APPENDIX 메시지도, AI 도구도 글쓰기에서 시작된다

A 이메일이나 메시지 쓰기 403

이메일 또는 남겨둘 메시지 쓰기 404

지시하고 응답하기 406

문제 상황 보고하기 408

 

B ChatGPT 활용하기 411

‘네가 해줘’ 말고 ‘도와줘’ 411

API 주석 쓰기 413

규칙 검사하기 419

 

도판 출처 426

[본 문]

커밋 범위를 잘 구성하면 제목을 수월하게 쓸 수 있는 것은 물론 혹여나 롤백(rollback)해야 할 상황이 발생했을 때 도움이 됩니다. 버그를 수정한 코드에서 새로운 버그가 파생됐다고 가정해봅시다. 롤백하면 문제가 발생한 코드는 제거할 수 있어도 UI 텍스트를 수정한 코드마저 빠지게 됩니다. 버그를 수정하는 코드와 UI 스트링을 수정하는 코드를 별도 커밋으로 올렸다면 UI 스트링을 수정한 버전은 지킬 수 있을 겁니다. (46쪽)

 

함수 이름을 짓기 어려울 땐 작업 순서를 바꿔 커밋할 메시지 제목을 먼저 작성해보세요. 메시지 제목을 보고 수행해야 할 기능 목록을 도출한 다음, 목록을 보고 함수 이름을 도출하는 겁니다. 간단한 기능이라면 제목만 보고 도출할 수도 있습니다. (74쪽)

 

오류 이름은 INVALID_ARGUMENT나 TEMPORARILY_UNAVAILABLE, Duplicated Id, Does not exist 같이 축약해서 만듭니다. 오류 설명은 오류가 발생한 원인을 문장으로 담습니다. 오류 메시지에 오류 원인이 문장으로 담겨야 사용자가 사태를 정확하게 파악할 수 있습니다. (104~105쪽)

 

예시 코드가 있다면 개발자 대부분은 코드부터 보고 설명글을 읽습니다. 그렇다 보니 예시 코드만 있으면 만사형통일 것으로 오해하기도 합니다. “어차피 코드를 보면 알 수 있는 내용을 왜 굳이 글로 써야 하느냐”라며 아무 설명 없이 코드만 잔뜩 늘어놓기도 하죠. (...) 잘 쓴 예시 코드는 완성된 샘플 프로그램 소스 코드를 통째로 붙여 넣은 것이 아닙니다. 특정 기능을 사용하는 법을 글로 잘 설명한 다음, 그 기능에 관한 코드만 추려서 넣어야 제대로 된 예시 코드라고 할 수 있습니다. 기능을 설명하는 데 초점을 맞추기 때문에 반드시 완성된 코드일 필요도 없습니다. 잘 작동하는 완성된 코드는 설명이 끝난 후 한꺼번에 보여주거나 별도 저장소로 제공하면 됩니다. (160쪽)

 

장애 내용으로는 장애 요약과 상세 설명으로 구분해 작성하세요. 장애 요약은 장애를 두세 문장으로 독자가 개발자가 아닐 수 있다는 점을 고려해서 이해하기 쉽게 작성하세요. 단순히 어느 제품 혹은 서비스에서 어떤 장애가 발생했다고만 적지 말고, 장애 때문에 사용자가 겪은 불편사항이 무엇인지 명확하게 드러내세요. 예를 들어 ‘트래픽이 증가해서 서버에 부하가 발생했다’로 끝내지 말고, ‘트래픽 증가로 서버 부하가 발생해 ○○ 서비스 사용자가 로그인할 수 없다’라고 작성하는 겁니다. (184쪽)

 

만약 새로운 용어나 약어 없이 도입부를 쓸 수 없다면 어떻게 해야 할까요? 이럴 때는 그 용어를 그대로 쓰되, 도입부에서 일일이 설명하기보다는 링크를 활용하는 편이 좋습니다. 예를 들어 도입부에 PSS라는 용어를 꼭 써야 한다면, 해당 용어를 설명한 다른 페이지(외부 사이트 또는 현재 문서 내 용어집, 관련 항목)를 링크하는 것입니다. 이렇게 하면 도입부 공간을 낭비하지 않으면서 새로운 용어를 안내할 수 있습니다. (370쪽)

단순히 글 쓰는 지식을 전달하는 것을 넘어 수많은 소프트웨어 기술 문서 프로젝트를 이끈 저자의 깊이 있는 경험과 통찰력이 고스란히 담겨 있습니다. 훌륭한 개발자가 되려면 뛰어난 소프트웨어 개발 능력뿐만 아니라 원활한 소통 능력도 필요합니다. 이 책이 여러분의 실무에 필요한 글쓰기 능력을 향상시켜 협업하는 동료, 여러분의 소프트웨어를 사용하는 고객과의 소통을 더 원활하게 만들어줄 것입니다.

강정일, LINE Plus Document Engineering팀 테크니컬 라이터

 

‘개발자’와 ‘글쓰기’. 동떨어져 보이는 개념이라 생각할지도 모르지만, 사실 개발자가 작성하는 코드부터 오류 메시지, 커밋 메시지, 릴리스 노트, 장애 보고서, 기술 블로그에 이르기까지 모두 ‘글쓰기’와 깊은 연관이 있습니다. 이 사실을 이미 알고 있고 그 중요성을 알고 있는 개발자라면, 이 책이 여러분이 원하는 모든 것을 제공해줄 것입니다. 그렇지 않은 개발자라도 괜찮습니다. 어차피 이 책이 그 중요성을 떠먹여줄 테니까요.

공슬기, 백엔드 개발자

 

기술 글쓰기에 호기심이 있거나 문서를 쓰면서 늘 무언가 아쉽다고 느꼈던 분들이라면 이 책이야말로 큰 도움이 될 것입니다. 그뿐 아니라 ‘내가 쓰는 기술 문서들… 뭔가 이상한데?’, ‘기술 관련 글을 쓰면 왠지 찜찜해’, ‘글 쓸 생각만 해도 막막해’ (가끔은 풀 리퀘스트 리뷰 앞에서 손이 떨릴 때도) 이런 마음이 들었던 분들이라면, 이 책이야말로 한 줄기 빛이 되어줄 것입니다. 이제 “테크니컬 라이터가 뭐예요?”, “기술 글쓰기를 잘하려면 어떻게 해야 하죠?”라는 질문에는 이 책 한 권으로 충분히 답할 수 있습니다. 만세!

권성환, CJ올리브영 테크전략지원팀장

 

개발자가 실제 업무에서 직면하는 다양한 글쓰기 유형을 체계적으로 정리하고, 이를 효과적으로 작성하는 방법을 명확히 제시합니다. 개발자와 글쓰기를 현실적이면서 실용적으로 다루고 있기에 모든 개발자가 책상 위에 두고 지속적으로 참고할 만한 귀중한 지침서로 자신 있게 추천합니다.

김유리, 삼성SDS 프로

 

이 책은 릴리스 노트, 커밋 로그, 변경 이력, 리드미 등 실제 개발 현장에서 자주 작성하게 되는 문서를 풍부한 예제와 함께 다루고 있어 현업 개발자뿐 아니라 오픈소스 프로젝트에 참여하는 분에게도 유용한 실전 안내서가 되어줄 것입니다. AI 시대에 ‘글쓰기가 여전히 필요한가?’라는 질문을 종종 듣습니다. 하지만 AI가 학습하는 원천 데이터는 결국 사람이 쓴 글입니다. 이 책이 소개하는 기술적 글쓰기는 시간이 지나도 그 가치를 잃지 않을 것입니다. 이 소중한 기회를 놓치지 않기를 바랍니다.

남정현, 마이크로소프트 MVP, 닷넷데브 대표

 

개발자의 글쓰기를 전문적으로 다룬 책은 많지 않습니다. 이 책은 단순한 글쓰기 가이드를 넘어 개발자의 성장을 위한 실용적인 전략서라고 할 수 있습니다. 개발자로서 한 단계 성장하고 싶은 분, 글을 통해 더 나은 협업을 만들어가고 싶은 분, 기술 블로그로 지식을 나누고 싶은 분들에게 이 책을 권합니다.

박조은, 오늘코드, 마이크로소프트 MVP

 

개발자를 위한 글쓰기 책은 꾸준히 출간되고 있습니다. 이는 새로운 글쓰기 기술이 등장한 것은 아니지만, 여전히 개발자의 글쓰기가 쉽지 않다는 것을 보여줍니다. 이 책은 단순히 글쓰기 이론을 설명하는 것이 아니라 현장에서 자주 만나는 다양한 문서와 글쓰기를 다루며, 개발자가 겪는 고민과 상황을 바탕으로 현실적인 조언을 담고 있습니다. 기술과 의사소통의 간극을 줄이고 싶은 모든 개발자에게 든든한 길잡이가 될 것입니다.

열이아빠, 테크니컬 라이터, 블로거

 

흔히 ‘개발자는 글을 못 쓴다’고 하지만, 사실은 ‘안 써서 못 쓰는 것’일 뿐입니다. 연습하면 누구나 잘 쓸 수 있다는 단순하고도 강력한 사실을 이 책은 초반부터 바로 짚어줍니다. 그렇다면 거창한 글이 아니라 아주 작은 것부터 연습해보면 어떨까요? 이 책은 커밋 메시지 쓰기, 함수와 변수 이름 정하기처럼 개발자가 일상에서 바로 시작할 수 있는 부담 없는 글쓰기부터 차근차근 이끌어줍니다. 작은 시도가 쌓이다 보면 글쓰기는 두려움이 아니라 자신감으로 바뀔 것입니다. 개발자가 글쓰기를 배우고 시작해야 한다면 그 출발점은 바로 이 책입니다.