[목 차]
추천의 글 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쪽)
코드만큼 중요한 문서, 이제는 쓰는 법도 알려드립니다
“개발자는 글을 못 쓴다?”
개발자들이 정말 글을 못 쓴다면 그 수많은 기술 문서와 블로그 글은 누가 쓴 걸까요? 모두 개발자가 쓴 글입니다. 매일 커밋 메시지를 쓰고, 변수명을 짓고, 리드미를 작성하고, 슬랙에 답하며 끊임없이 글을 씁니다. 그럼에도 많은 개발자가 글쓰기를 어려워합니다. ‘무엇을’, ‘어떻게’ 써야 할지 배운 적이 없기 때문입니다.
이 책은 그 막막함에 실전적인 답을 줍니다. 커밋 메시지를 한 줄로 깔끔하게 쓰는 법, 변수명과 함수명을 더 명확하게 짓는 원칙, 오류 메시지와 주석을 사용자 입장에서 다듬는 방법, 리드미와 시작하기 문서를 쉽게 구성하는 법, 기술 블로그로 설명력을 높이는 팁까지 실무에 바로 쓸 수 있는 글쓰기 전략을 실제 사례와 함께 설명합니다. 여기에 이메일과 슬랙 메시지처럼 협업에 꼭 필요한 글쓰기부터 ChatGPT에게 제대로 묻고 설명하는 프롬프트 작성까지 지금의 개발자에게 꼭 필요한 기술적 글쓰기를 폭넓고 깊이 있게 다룹니다.
개발자는 글을 못 쓴다? 아니요. 이 책과 함께라면 개발자도 글을 잘 쓸 수 있습니다.
주요 내용
커밋 메시지, 오류 메시지, 주석을 명확하게 쓰는 법
변수명과 함수명을 잘 짓기 위한 작명 원칙
리드미, 릴리스 노트, 시작하기 문서의 실전 구성법
기술 블로그와 예제 코드로 설명력을 높이는 방법
정확하고 간결한 기술 문서를 쓰는 세 가지 기법
이메일, 메시지 잘 쓰는 법과 ChatGPT 활용 팁