이 리뷰는 광고나 협찬 없이 작성한 개인적인 후기입니다.
들어가며
회사에서 매주 진행하는 FE 챕터 발표 시간에 동기 분이 이 책을 소재로 발표를 해주셨어요. 그때 들었던 내용이 너무 실용적이고 흥미로워서 바로 그 분께 책을 빌려 읽게 되었습니다. 개발자라면 누구나 코드만큼이나 자주 마주하게 되는 '글쓰기'에 대한 구체적인 가이드라인을 담고 있어서, 읽는 내내 "아, 이런 부분에서 내가 헤매고 있었구나" 하는 깨달음이 많았던 것 같아요.
목차
저자의 말
1부 테크니컬 라이팅 시작하기
1장 테크니컬 라이팅
테크니컬 라이팅과 기술 문서테크니컬 라이팅과 일반 글쓰기의 차이테크니컬 라이팅 5단계
2장 개발자와 테크니컬 라이팅
개발자와 테크니컬 라이팅그냥 쓰는 것이 아니라 제대로 쓰기
2부 테크니컬 라이팅 45가지 원칙
3장 문서 작성 계획 세우기
01 대상 독자를 정한다
02 설명할 기술의 깊이를 조절한다
03 분위기를 좌우할 어조를 정한다
04 주제를 구체적으로 정한다
05 작성할 문서의 종류를 정한다
4장 초안 작성
06 일단 쓴다
07 명확성, 간결성, 일관성의 3원칙
08 핵심부터 쓴다
09 제목에 요점을 담는다
10 문장 하나에는 주제를 하나만 쓴다
11 객관적인 근거를 댄다
12 전문 용어는 독자에 맞게 사용한다
13 용어와 약어를 쓸 때는 풀이를 쓴다
14 용어는 일관되게 사용한다
15 쉽게 쓴다
5장 시각화 요소로 가독성 높이기
16 적합한 시각 자료를 활용한다
17 목록을 사용해 정리한다
18 스크린숏으로 이해도를 높인다
19 정보를 비교할 때는 표를 활용한다
20 데이터 성격에 맞는 차트를 사용한다
21 시각 자료를 쓰기 전에 소개부터 한다
22 시각 자료를 설명하는 캡션을 활용한다
6장 검토와 재작성
23 객관적으로 문서를 검토한다
24 맥락에 맞는 적확한 단어를 선택한다
25 은어는 형식적인 표현으로 바꾼다
26 대명사는 일반 명사로 바꾼다
27 고유한 이름은 정확히 쓴다
28 숫자와 단위를 정확하게 쓴다
29 단정적인 어조로 확신 있게 쓴다
30 글꼬리를 뚜렷하게 쓴다
31 주어와 서술어를 일치시킨다
32 문장은 짧게 줄인다
33 군더더기 표현을 없앤다
34 의미가 같은 표현은 한 번만 쓴다
35 피동태보다 능동태로 쓴다
36 복잡한 번역체를 다듬는다
37 ‘통해’는 명확한 표현으로 바꾼다
38 ‘무엇은 ~ 무엇이다’ 형식으로 쓰지 않는다
39 ‘~해 주다’ 대신 ‘~하다’를 쓴다
40 조사를 덜어낸다
41 재작성한 문서를 동료와 검토한다
42 자주 틀리는 맞춤법
43 자주 틀리는 외래어 표기법
44 자주 틀리는 띄어쓰기
45 자주 틀리는 문장 부호
3부 유형별 테크니컬 라이팅 사례로 본 작성의 원칙
메일ㆍ회의록ㆍ장애 발생 공지문ㆍ사용자 가이드
7장 메일 작성
46 받는 사람이 궁금해할 내용을 쓴다
47 인사말과 맺음말은 과하지도 부족하지도 않게 쓴다
48 받는 사람을 명확하게 지정한다
49 첨부 파일을 확인한다
8장 회의록 작성
50 회의록 구성 요소를 확인한다
51 회의록 작성 원칙을 기억한다
9장 오류와 확인 메시지 작성
52 확인 메시지 작성법
53 오류 메시지에서 중요한 것은 해결 방법
54 메시지에서도 제목을 활용한다
55 직관적인 버튼 텍스트를 만든다
10장 장애 발생 공지문 작성 1부
56 장애 발생 공지문의 기본 요소: 장애 발생 직후
57 장애 해결 공지문의 기본 요소: 장애 해결 후
58 장애 보고서 작성: 내부 보고와 기록용
11장 사용자 가이드 작성
59 사용자에게 맞는 가이드 종류를 선택한다
60 개념과 목적을 설명하는 개요를 추가한다
61 사용법은 순차적으로 설명한다
62 퀵스타트 가이드로 제품과 빠르게 친숙해지게 한다
주요 내용
이 책은 크게 3부로 구성되어 있어요. 1부에서는 테크니컬 라이팅의 기본 개념과 일반 글쓰기와의 차이점을 다루고, 2부에서는 실무에서 바로 적용할 수 있는 45가지 구체적인 원칙을 소개합니다. 3부에서는 메일, 회의록, 장애 발생 공지문, 사용자 가이드 등 개발자가 자주 작성하는 문서 유형별 작성법을 실제 사례와 함께 보여줘요.
인상 깊었던 것 중 하나가 '역피라미드 방식'이라는 개념이었어요. 결론을 먼저 제시하고 배경과 근거를 뒤에서 설명하는 방식인데, 그동안 저는 왜 이런 결과가 나왔는지 설명하려다 보니 앞부분이 길어지는 경우가 많았거든요. 앞으로는 핵심을 먼저 말하고 근거를 차례로 설명하는 방식을 써봐야겠다고 생각했습니다.
문장 작성에 대한 조언도 실용적이었어요. '문장 하나에는 주제를 하나만'이라는 원칙이 특히 와닿았는데, 접속사를 계속 써가며 문장을 늘어뜨리는 제 습관을 돌아보게 되었어요. 소리 내어 읽으면서 짧게 나눌 수 있는 문장은 짧게 나누는 연습을 해야겠다는 생각이 들었습니다. 시각 자료 활용법도 눈여겨볼 만했어요.
그림이나 코드를 넣기 전에 무엇에 관한 내용인지 미리 설명해야 한다는 점, 스크린숏 위에 텍스트를 추가하지 말라는 조언 등은 바로 적용할 수 있는 팁이었습니다. 그동안 그림을 넣기 전에 설명할지, 아래에 설명할지 참 고민이 많았었는데 명확한 기준을 얻을 수 있었어요. '독자가 당황할 수 있으니 어떤 그림, 코드인지에 대해서 먼저 설명을 해주고 첨부를 하는 것이 좋다' 였어요.
언어 사용법에서도 많은 것을 배웠습니다. 개발자 은어는 피하고, '여기를 참고하세요' 같은 대명사 대신 'API 레퍼런스를 참고하세요'처럼 구체적으로 명시하라는 조언이 특히 유용했어요. '진행', '처리', '발생' 같은 군더더기 표현이나 '~에 대해', '~을 통해' 같은 번역체도 줄여야겠다고 다짐했습니다.
특징
이 책의 가장 큰 장점은 추상적인 조언이 아닌 구체적이고 즉시 적용 가능한 원칙들로 가득하다는 점이에요. 각 원칙마다 좋은 예시와 나쁜 예시를 함께 보여줘서 이해하기 쉽고, 실제 개발 현장에서 자주 마주하는 상황들을 다루고 있어 실용성이 높습니다.
추천 이유와 대상
문서 작성이 업무의 상당 부분을 차지하는 개발자라면 누구에게나 도움이 될 것 같아요. 특히 주니어 개발자나 테크니컬 라이팅에 막 발을 들인 분들에게는 체계적인 가이드가 되어줄 수 있을 것 같습니다.
팀 내에서 문서 작성 기준을 정하고 싶은 개발팀 전체가 함께 읽어보기에도 좋습니다. 꼭 개발자가 아니더라도 업무용 문서를 자주 작성하는 직군이라면 충분히 활용할 수 있는 내용들이에요.
마치며
책을 읽으면서 그동안 무의식적으로 해오던 글쓰기 습관들을 객관적으로 돌아볼 수 있었어요. 점 목록을 남발하던 습관, 불필요하게 긴 문장을 쓰던 버릇 등을 자각하고 개선점을 찾을 수 있었습니다. 무엇보다 좋았던 건 바로 실무에 적용할 수 있는 구체적인 방법들을 얻었다는 점이에요. 앞으로 회사에서 문서를 작성할 때 이 책에서 배운 원칙들을 하나씩 적용해보려고 합니다. 글쓰기가 어렵게만 느껴졌던 개발자 분들께 정말 추천하고 싶은 책이에요!
좋은책 읽어볼 수 있도록 빌려주신 노바, 감사드립니다 :)
