[리뷰#1] 개발자를 위한 글쓰기 가이드

http://www.yes24.com/Product/Goods/97584812

개발자가 코딩만 잘하면 된다? 고객의 요구사항 분석을 제대로 글로 옮기지 못한다면 무슨 일이 발생할까? 장애 발생 시 공지문을 작성해야 하는데, 빠짐없이 정확하게 작성할 수 있을까? 오류와 확인 메시지는 제대로 쓸 수 있을까? UI에 들어가는 텍스트는? 소프트웨어 제품 출시 후 사용자 가이드는 어떻게 만들어야 할까?

개발자는 코딩 영역 외에도 이렇게 수많은 글쓰기 문제에 직면한다. 이를 위해 저자는 테크니컬 라이터로서 20년 이상 개발자와 함께하며 얻는 핵심 노하우를 이 책 한 권에 정리하였다. 옆에 두고 항상 참고할 수 있는 개발자만을 위한 글쓰기 가이드이다.

 

테크니컬 글을 작성하고 싶다면, 도움이 될 책입니다. 글을 자주 쓴다면 집에 하나씩 놔두고 유용하게 사용할 수 있을 것 같습니다. 그만큼 실용적인 팁들이 많아요. 

 

추천 독자는 테크니컬 라이팅을 시작하려는 개발자, 혹은 메일/회의록 등의 문서를 작성하는 데 어려움을 느끼는 사람들입니다. 본인이 '글을 자주 쓴다'라고 생각한다면, 챙겨놔서 나쁠 것 없는 책입니다. 

 

총 3부로 이루어져 있는데,  1부는 테크니컬 라이팅에 대한 소개,  2부는 테크니컬 라이팅의 45가지 원칙, 마지막으로 3부는 유형별 테크니컬 라이팅 원칙입니다. 아래는 책을 읽으면서 나중에 쓸 수 있을만한 팁들을 간단하게 정리했습니다. 물론 책이 훨씬 자세하고 예시도 많으니 직접 읽으면 더 좋습니다. 

1부. 테크니컬 라이팅 시작하기

- 테크니컬 라이팅이란?

기술이나 과학 분야에서 정보를 정확하게 전달하기 위한 글쓰기.

 

- 테크니컬 라이팅 5단계

1. 계획 세우기

2. 구조 잡기

3. 초안 작성

4. 검토와 재작성

5. 배포 

2부. 테크니컬 라이팅 45가지 원칙

10. 문장 하나에는 주제를 하나만 쓴다

[수정 전]

기획자와 개발자는 같은 기획서를 서로 다르게 해석하곤 하는데, 기획서를 잘 만들었다고 해도 개발자 입장에서는 불명확한 부분이 생길 수밖에 없다.

[수정 후]

개발자는 기획자와는 다른 방법으로 기획서를 해석한다고 한다. 
그래서 기획자가 아무리 기획서를 잘 만들어도 개발자에게는 불명확한 부분이 생길 수 밖에 없다. 

 

23. 객관적으로 문서를 검토한다

[문서를 검토할 때 확인해 볼 내용]

항목

내용에 맞는 제목을 달았는가?

목차가 올바른가?

용어를 일관되게 사용했는가?

이해하기 어려운 용어는 없는가?

필요한 정보가 모두 있는가?

불필요한 정보가 있지는 않은가?

내용을 찾기 쉽게 목차를 구성했는가?

단락은 적절히 나누었는가?

중복 내용은 없는가?

표현이 명확한가?

객관적인 근거가 있는가?

출처가 명확한가?

외국어나 한자어가 많지 않은가?

피동태가 많지 않은가?

그림이 적절하게 배치됐는가?

표를 적절하게 사용했는가?

 

45. 자주 틀리는 문장 부호

- 마침표(.)

1. 문장을 마칠 때 마지막에 쓰는 문장 부호

2. 연월일을 대신해 나타낼 때 아라비아 숫자 뒤에 사용

3. 장, 절, 항 등을 표시하는 문자나 숫자 다음에 사용

1. 시작하기
1.1. 앱 설치
2020. 12. 26.

 

- 쌍점(:)

1. 시간에서 시와 분, 분과 초를 구분 할 때

2. '몇 대 몇'과 같이 쓸 때 '대' 대신에 사용

3. 문서에서 부제목을 나타낼 때도 쌍점을 사용

12:25:52
4:1로 앞선 상황
개발자를 위한 테크니컬 라이팅 가이드: 50가지 팁

 

- 물결표(~)

1. 기간이나 거리 또는 범위를 나타낼 때 사용(공백 없이)

2. 다른 말이 덧붙을 수 있음을 표시하거나 이를 생략했음을 나타낼 때 사용

2시~6시
메일에서 '회의록은 ~ 참고하세요.'를 확인해 주시기 바랍니다. 

 

- 큰따옴표(" ")

1. 낱말이나 문장을 직접 인용할 때 사용

2. 책 제목, 신문 이름을 나타낼 때도 사용

배달 앱 기획자는 "앱을 직관적으로 사용할 수 있게 하는 것이 목표였습니다." 라고 말했다.
2021년에 출간된 "테크니컬 라이팅 기본"은 개발자가 글을 쓸 때 참고하면 좋은 책이다.

 

- 작은따옴표(' ')

1. 문장의 중요한 부분을 강조할 때 사용

2. 예술 작품의 제목, 상호, 법률, 규정 등을 나타낼 때 사용

3. 인용한 말 안의 인용한 말을 나타낼 때 사용

"시각 자료를 활용하면 이해도가 높아집니다. '백문이 불여일견'이라는 말도 있듯이 말입니다."
데이터를 서로 비교할 때는 '표'를 사용하면 좋습니다.
문장부호 사용법은 '문장부호 바로 쓰기' 절을 참고합니다.

 

- 소괄호( )

1. 보충할 내용을 덧붙일 때

2. 우리말 표기와 원어 표기를 같이 쓸 때

3. 생략할 수 있는 내용을 나타낼 때

이 책은 테크니컬 라이팅(기술 글쓰기)에 대해 다룬다.
스미싱(smishing)은 문자 메세지를 사용한 피싱 방법이다.
변수 뒤에 조사를 쓸 때는 '을(를)', '이(가)'와 같이 씁니다.

3부. 유형별 테크니컬 라이팅 사례로 본 작성의 원칙

- 메일

[메일 발송 전 체크리스트]

항목

메일에 제목을 썼는가?

받는 사람에 업무를 할 사람을 지정했는가?

참고로 정보를 알아야 하는 사람을 모두 참조에 넣었는가?

인사말이 너무 길지는 않은가?

내 이름을 밝혔는가?

상대방 이름이나 고유 명사를 정확하게 썼는가?

필요한 파일을 첨부했는가?

기밀 데이터나 개인 정보가 포함돼 있지 않은가?

 

- 회의록

[회의록 예시]

2020년 12월 1주 차 개발기획팀 주간 회의록

- 일시: 2020. 12. 3.(목) 15:00~15:40
- 장소: 11-2 회의실
- 참석자: 개발기획팀 나길동, UI디자인팀 강소리, 개발팀 한두리
- 불참자: 편희영(외부 교육)
- 회의 내용
  1. Google Play 새 아이콘 앱 정책 적용 협의
     - 새 아이콘 적용 안내문 공지: 강소리(~12. 8.)
     - 새 아이콘 디자인 완료: UI디자인팀 강소리(~12. 11.) 
     - 새 아이콘 적용: 개발팀 한두리(~12. 17.)
  2. 사내 메일 장애 보고서 공유: 개발팀 한두리(~12. 22.)
- 기타
  2월 말쯤 부서 워크숍 예정. 장소와 정확한 날짜는 추후 공지