도서관에 갔다가 ‘개발자를 위한 글쓰기 가이드’ 란 책을 우연히 빌리게 되었다.
개발자가 글쓸일이 많이 있나 싶었는데…
생각해 보니 메일도 쓰고 있고, 개발 산출 문서도 작성하고,
심지어 지금도 글을 쓰고 있다.
개발자의 글쓰기는 어떤 것일까?
테크니컬 라이팅
책에서는 ‘테크니컬 라이팅’에 대해서 다루고 있다.
테크니컬 라이팅 이란?
책에서는 ‘기술이나 과학 분야에서 정보를 정확하게 전달하기 위한 글쓰기‘라고 설명 하고 있다.
일반 글쓰기와 비교하면 아래와 같다.
| 일반 글쓰기 | 테크니컬 라이팅 |
|---|---|
|
|
테크니컬 라이팅의 5단계
테크니컬 라이팅 과정은 크게 아래의 5단계로 나눌 수 있다.
- 계획세우기
- 구조잡기
- 초안작성
- 검토와 재작성
- 배포
얼핏보면 개발과정과 비슷한 느낌이다.
- 요구사항 분석 및 시스템 명세를 작성 하고,
- 시스템 설계를 하고,
- 프로그래밍 후
- 테스트 과정을 거친 후
- 서버 배포
각 단계별로 상세히 알아보자.
계획세우기
독자를 정하기
테크니컬 라이팅은 ‘누군가’에게 정보를 전달하는 것이 목적이라, 독자를 정하는 것이 중요하다.
독자가 정해지면 독자의 수준에 따라 어떻게 설명할 것인지를 고민한다.
예를 들면 비 개발자에게 개발용어로 설명을 한다면 전혀 정보가 전달 되지 않을 것이다.
추가로 대상 독자와 문서의 목적이 정해 졌다면, 어조를 결정한다.
사용자 층에 따라 부드러운 어조로 할 것인지, 형식적인 어조를 할 것인지를 결정한다.
그리고 문서내에서는 동일한 어조를 사용하는 것이 좋다.
주제를 정하기
정보를 전달하고자하는 범위를 좁혀 어떤 정로를 전달할 지 주제를 명확하게 정해야 한다.
예를 들어 두루뭉실하게 ‘웹 개발 가이드’ 라고 써버리면 어떤 설명을 작성 해야할지 범위가 너무 커져버린다.
초안작성
독자와 주제가 정해 졌으면 초안을 작성해 보자.
한 번에 완성 하려기 보단 일단 문서를 작성하고, 반복해서 검토 과정을 거친다.
역피라미드 방식
문서 작성 시에는 전달 하고자하는 주제를 먼저나오고, 주제를 뒷바침하는 근거나 설명등을 뒤에 덧붙인다.
예를 들어 내부에서 사용 할 장애보고에 대한 글을 작성한다고 할 때
금일 장애가 발생해서 많은 분들에게 심려를 끼쳐 드렸습니다.
테스트 시에 오류가 발생하는 것을 확인했어야 하는데…
금일 메일 발송서비스에 장애가 발생하였습니다. 장애 발생 일시: 2021-08-12 12:00 ~
영향받은 서비스: 메일 발송 서비스 장애 원인: …
아래와 예시와 같이 핵심 주제가 앞 부분에 나오게 되면, 전체를 읽지 않더라고 문서의 내용을 빠르게 파악 할 수 있다.
이런 글쓰기 방식은 역피라미드 방식이라고 한다.
- 역피라미드 방식
- 주제: 전하려는 핵심이 처음에 온다.
- 중요한 사실: 주제를 설명해 주는 내용이 온다.
- 예시: 주제, 중요한 사실을 증명해주는 예시, 자료, 논문 등이 나온다.
위의 연장 선상에서 구체적으로 내용을 파악할 수 있게, 제목은 문서의 요점을 파악할 수 있도록 구체적으로 명시한다.
명확성, 간결성, 일관성
문장은 간결하고 쉽게, 하나의 주제만 담기도록 쓴다.
하나의 문장에 여러 개의 주제가 있으면 문장의 내용을 파악하기 어려워 진다.
증명
객관적인 근거를 댄다.
- 잘못된 예: A서버보다 B서버에서 로딩하는 속도가 훨씬 빨랐다.
- 올바른 예: 파일을 로딩할 때 A서버를 이용하면 1.5초, B서버를 이용하면 0.9초가 걸렸다.
용어
전문 용어는 독자에 맞게 사용한다.
용어와 약어를 쓸 때는 풀이를 쓴다.
용어와 표현은 문서 내에서 일관되게 사용한다.
시각화 요소
시각 자료를 활용하면, 문서의 가독성을 높일 수 있다.
시각 자료를 쓰기 전에 관련 설명을 기재한다.
그리고 시각 자료를 설명하는 캡션을 활용하는 것이 좋다.
검토와 재작성
테크니컬 라이팅 과정에서 제일 중요하고, 오랜 시간을 투자해야 한다.
시간을 두고 검토하거나, 타인에서 검토를 부탁하는 것도 좋은 방법이다.
검토 시 확인할 사항 예시
검토할 사항들을 체크리스트로 만들어 두고, 객관적으로 검토하는 것을 추천한다.
- 오탈자, 문법 오류는 없는가?
- 용어를 일관 되게 사용했는가?
- 중복 내용은 없는가?
- 불필요한 정보가 있지 않은가?
- 은어를 사용하고 있지 않은가?
- 숫자와 단위를 정확하게 사용했는가?
- 군더더기 표현은 없는가?
- 피동태를 자주 사용하였는가?
여기에 소개는 못했지만 문서 별 가이드, 그리고 각 단계별로 상세 가이드 등이 잘 나와있어서 한번쯤 읽어 보는걸 추천 드립니다.