개발자를 위한 글쓰기 가이드

이번에 읽은 책

개발자 혹은 프로그래머는 코딩, 개발만 하면 된다고 생각하기 쉽지만

개발 업무를 하다보면 생각보다 많은 문서를 작성하게 된다. (예를 들어 이메일, 매뉴얼, 설계도 등)

이 책은 이러한 크고 작은 문서를 작성할 때 지켜야할 가이드라인을 제시한다.

다 읽고서 느낀점은, '무조건 이 책을 따라해라!' 하는건 아니다.

하지만 이렇게 해도 되나? 하고 감이 안잡힐땐 이 책의 가이드라인을 따라해도 될 것 같다.

 

그리고 내가 느낀바로는 이 책의 내용은 비단 문서 작성에서만 사용하는 것이 아니다.

 

개발 업무를 하다보면 비전공자를 대상으로 이야기할 때도 많고, 같은 전공자라도 전문 분야가 다른 경우가 너무 많다.

그럴때도 항상 듣는 청취자(읽는 독자)의 지식수준을 생각하여 가이드라인을 생각하며 이야기해야 한다. 

 

책은 다 읽었으니 시간을 들여서 책 내용을 정리해 봐야겠다.

 

이미 실무에 있는 사람들은 요약만 둘러봐도 공감이가겠지만, 요약본으로 이해를 못하겠다면 책을 한번 사 보도록 하자.예제가 많다.

(근데 요즘 책 너무 비싸다. 나쁜 정가제..)

---

일반 글쓰기와 기술 글쓰기의 차이

일반 글쓰기	기술 글쓰기
- 창의 - 상징 - 자유 흐름 - 일반인 대상	- 사실 - 직설 - 순차적 흐름 - 특정인 대상

테크니컬 라이팅 5단계

1단계	2단계	3단계	4단계	5단계
계획 세우기	구조 잡기	초안 작성	검토 및 재작성	배포

 

1단계: 계획 세우기

1) 대상 독자를 정한다.

대상 독자의 지식 수준에 맞게 내용을 설명하여야 한다.

개발 관련 글을 쓸때는 다음과 같이 직무를 기준으로 고려하는 것이 유용하다.

• 개발자
• 개발은 하지 않는 기술 관련 업무자
• 개발 관련 전공 대학생
• 개발 관련 전공 대학원생
• 개발자가 아닌 홍보나 마케팅 담당자

내 생각엔 이게 이 책에서 제일 중요한 내용이 아닌가 싶다.
이건 글을 쓸때 뿐만이 아니라, 업무 협조를 할때도 꼭 필요한 사항이다.

2) 설명할 기술의 깊이를 조절한다.

Android SDK를 설명할 때, SDK가 무엇인지, Android가 무엇인지 까지 설명해야하나 말아야하나를 결정해야 한다.

 

2단계: 구조 잡기

1) 분위기를 좌우할 어조를 정한다.

무조건은 아니지만 불특정 다수가 보는 내용이라면 ~있어요. 와 같은 친근한 어조를 사용하고, 개발 문서와 같은 특정 직무나 특정인만 볼 수 있는 내용이라면 ~하십시오. 같은 형식을 따르는게 좋다.

• 파일 이름을 마음대로 바꿀 수 있어요.
• 파일 이름을 원하는 대로 변경할 수 있습니다.

나는 개인적으로 1:1로 이야기 할때는 ~있어요.
1:n(강연 등) 또는 글로 쓸때는 ~습니다, ~하십시오가 더 좋은 것 같다.

2) 주제를 구체적으로 정한다.

주제가 너무 포괄적이거나 너무 국소적이지 않은지 생각해 보자.

예문	수정안
GitHub 사용법	GitHub에서 레파지토리 생성 방법.

GitHub의 기능이 얼마나 많은데, 그걸 다 쓸 수있나?

3) 작성할 문서의 종류를 정한다.

• 메일
• 회의록
• 보고서
• 가이드
• 튜토리얼

3단계: 초안 작성

1) 일단 쓴다.

처음부터 완벽한 문서를 만들려고 해서는 안된다.

내가 맨날 이러다가 힘빠져서 완성을 못하거나 용두사미가 된다.

2) 명확성, 간결성, 일관성의 3원칙

명확성	간결성	일관성
단정적이지 않거나 추측성 표현을 사용해서는 안된다. 단호하고 명확하게!	문장이 짧아야 정보전달이 빠르다. 그렇다고 혼자 알아보는 독자가 알지못하는 약어를 사용하지 않도록 주의 해야한다.	앞에서 설명한 내용이 뒤에서 설명한 것과 달라지면 안된다. 특정 용어나 설명 방법도 일관되어야 한다.

그 외에 5원칙이나 7원칙에 대한 내용도 책에는 있으니 참고하자.

3) 핵심부터 쓴다.

글을 두괄식 혹은 역피라미드 방식으로 구성해야한다.

결론, 핵심, 주제부터 쓰고 근거나 데이터를 설명하는 방식.

이렇게 써야하는 이유는 다음 예제만 봐도 알 수있다.

안녕하세요. 쿠폰 서비스팀입니다. 지난 10월, 쿠폰 서비스를 12월 9일에 오픈한다고 공지했습니다. 사전에 공지드린 대로라면 다음 주에 새 쿠폰 서비스를 선보여야 하는데요. 조금 더 안정화된 모습을 부여드리려면 충분한 테스트를 거쳐야 한다고 판단하여 오픈일을 1월 13일로 연기하기로 했습니다. 기다리신 분들의 너른 양해를 부탁드리며, 좋은 서비스로 보답해 드리겠습니다. 감사합니다.

결국 결론은 서비스 오픈을 1월 13일로 연기한다. 인데 이걸 알려고 몇 번째 줄까지 읽어야 하는거야?

4) 제목에 요점을 담는다.

요점을 너무 압축하거나 생략하지 않도록 한다.

예문	수정안
검색 및 기본 정보	ID로 사용자 검색하기 ID로 사용자 정보 확인하기

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

6) 객관적인 근거를 댄다.

A보다 B가 빠릅니다. 보다는 A보다 B다 0.5초 빠릅니다.

7) 전문 용어는 독자에 맞게 사용한다.

8) 용어와 약어를 쓸 때는 풀이를 쓴다.

9) 쉽게 쓴다.

옆사람에게 말하듯이 글을 써보자.

 

3+@: 시각화 요소

내 생각엔 이 부분은 이론이라기 보단 일종의 노하우 이기도하고, 글로만 요약하기는 힘들다.
그래서 몇가지 빼고는 제목만 쓰도록 하겠다.
나중에 내가 이것만 봐도 기억할 수 있도록..

1) 적합한 시각 자료를 활용한다.

100자리 글자보다 1장의 사진이나 표, 그림이 더 좋을때가 많다. 특히 무언가를 설명할 때.

2) 목록을 사용해 정리한다.

• 이런거
• 말하는
• 거다

목록도 숫자목록이 있고 점 목록이 있는데, 각각 용도가 다르다.

3) 스크린숏으로 이해도를 높인다.

여기서 중요한건 스크린숏이나 그림안에 텍스트를 넣어선 안된다.

나중에 번역하거나 수정하기가 힘들다.

충격적이게도 스크린샷이 아니라 스크린숏이 맞는 표현이라고 한다.

4) 정보를 비교할 때는 표를 활용한다.

5) 데이터 성격에 맞는 차트를 사용한다.

차트 모양에 따라 표현하기 좋은 주제가 있다.

6) 시각 자료를 쓰기 전에 소개부터 한다.

7) 시각 자료를 설명하는 캡션을 활용한다.

이런거 말하는거다.

그림 1 블로그의 카테고리를 설정하는 방법.

4단계: 검토와 재작성

 

여기다가 쓸꺼야.

 

 

 

---

Hisoty....

2021.05.10. 최초 작성

2021.05.11. 1단계 계획세우기 ~ 2단계 구조잡기

2021.05.12. 3단계 초안작성 ~ 3+@단계 시각화

(미완성)