👀

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

2021.09.02 ~

📌 문서 작성 계획 세우기

✨ 독자 분석 체크 리스트

독자가 원하는 것은 무엇인가?
독자는 이 문서를 보고 무엇을 하려 할까?
독자의 기술 수준은 어떻게 되나?
독자가 이미 알고 있는 정보는 무엇인가?
어떤 직업, 어떤 직위에 있는 사람인가?
독자의 학력과 전문 용어 이해 수준은 어느 정도인가?
저자와 독자는 어떤 관계가 있는가?
주제에 관해 독자가 이미 알고 있는 사실은 어떤 것인가?
독자가 이 글을 이해하는 데 필요한 사전 정보는 무엇인가?
독자에게 어떤 반응을 기대하는가?

✨ 설명할 기술의 깊이 조절하기

예시

여기에서는 **(전문 용어 o)을 설명한다.
**은 **을 하는 역할을 한다. 여기에서는 특히 **에서 사용하는 **을 다룬다.
여기에서는 ~~(전문 용어 x)을 어떻게 확장할 수 있는지 알아보겠다.

비개발자

이미 익숙해서 기본 개념에 대한 설명을 빼먹기 쉬우므로 이 점을 유의하자. 글을 쓰고 반드시 독자 관점에서 읽어 보고, 빠진 내용은 없는지 검토하자

개발자

일반적인 용어 설명은 하지 않아도 된다. 기초적인 내용을 길게 한다면, 오히려 지루해진다.

비개발자 & 개발자

각 독자 수준에 맞춰 일단 내용을 모두 작성하자. 필요한 정보만 선택해 볼 수 있게 목차를 활용하자. 문서 앞부분에 독자별로 읽을 장이나 절을 따로 소개하자.
예시) 해당 부분이 익숙하다면 본론으로 넘어가도 좋습니다.

✨ 어조 정하기

어조를 정하고 문서 전체에서 일관되게 사용해야 한다.

📌 초안 작성하기

✨ 일단 쓰자

쓰고 싶은 내용 모두 쓴다. 채우다 보면 생각을 정리할 수 있고 추가할 내용이 떠오를 수 있다. 맞춤법이나 문법은 넘어가자. 전달해야 할 내용을 빠짐없이 추가하는 데에만 집중하자.

✨ 3대 원칙 생각하기

명확성

다루는 내용이 정확하고 전달하는 방식과 표현도 선명해야 한다. 단정적이지 않은 표현과 추측성 표현 등은 신뢰를 주기 어렵다.

간결성

문장은 짧게 유지해야 한다. 단락 역시 5개 안팎의 문장으로 구성하자. 짧고 쉽게 쓰도록 신경쓰자.

일관성

문서 전체에서 설명하는 내용이 일관돼야 한다. 같은 의미의 용어나 설명 방법도 일관되게 유지해야 한다.

✨ 핵심부터 쓰자

핵심부터 적고 내용을 뒷받침하는 근거나 설명을 덧붙이자. 답을 먼저 제시하고 배경과 근거를 이후에 설명하는 '역피라미드 방식'으로 작성하자.
역피라미드 방식 결론, 핵심, 주제부터 제시하고 근거나 데이터를 설명하는 방식을 말한다. 중요한 내용을 문서 앞부분에 설명하고, 덜 중요한 내용을 차례로 배치하자. 마지막에는 참고 자료나 정보를 추가한다.

✨ 제목에 요점을 담자

요점을 압축해 제목으로 쓰자. 명사만 나열하면 명확하게 전달하기 어렵기 때문에 명사와 명사 사이에 필요한 조사와 동사를 추가하자.

✨ 제목 작성 체크리스트

내용이 무엇인지 한눈에 알 수 있는가?
부제목이 필요하지 않은가?
목적과 방법을 명확하게 알 수 있는가?
명사만 나열하지 않고 의미를 정확하게 서술했는가?
널리 알려지지 않거나 표준이 아닌 약어를 사용하지는 않았는가?

✨ 문장 하나에는 주제를 하나만 쓰자

전달하고 싶은 내용이 한 문장에 있으면 파악하기 어렵다. 짧게 유지해서 읽기 쉽게 만들자.

✨ 객관적인 근거를 대자

사실을 전달하거나 주장을 펼칠 때, 듣는 사람의 동의를 이끌어 내려면 근거를 제시하면 효과적이다. 특히 수치 데이터를 제시하면 효과적이다.
예시) 매우 빨랐다 → 0.9초가 걸렸다.
즉, 객관적인 수치나 근거를 제시해야 글의 신뢰도가 높아진다.

✨ 용어는 일관되게 사용하자

하나는 한국어, 하나는 영어로 표현하면 혼동이 생길 수 있어 일관되게 사용하자. 독자가 0.1초라도 더 생각하게 만들지 않아야 한다. 되도록 한글로 사용하며, 한글로 사용하기 어렵다면 음차해서 사용하자. 음차는 언어의 소리를 문자로 표기한 것을 의미한다.

📌 시각적인 요소로 가독성 높이기

시각 자료(목록, 표, 그림, 차트 등)는 정보를 오래 기억할 수 있고, 쉽게 이해할 수 있다. 길게 문장으로 설명하는 것보다, 시각적인 자료를 보여주는 것이 빠를 때도 있다. 아래 경우에 시각 자료를 사용하는 것이 효과적일 수 있기 때문에 참고하자.
그림이 없으면 설명이 복잡하고 길어지는 경우
복잡한 설정이 필요한 경우
화면을 가리키면서 정보를 제공하는 경우

✨ 목록 사용하기

점 목록

순서 상관없이 나열하할 때 적합하다. 주의할 점은 아래와 같다.
각 항목의 성격이 대등해야 한다.
다른 항목에 종속된다면 같은 수준의 점 목록을 사용하지 말아야 한다.
일반 문장으로 풀어 써야 하는 곳에 습관처럼 사용하지 말아야 한다.

번호 목록

순서가 중요할 때 적합하다.

✨ 스크린샷으로 이해도를 높이자

꼭 필요할 때만 넣자. 단순한 설명이라면 넣지 않아도 된다.
필요한 부분만 잘라서 넣자. 만약 화면의 텍스트를 참고해야 할 때는 텍스트가 잘 보여야 한다.
캡쳐 환경을 통일하자.
그림 크기를 일관되게 지정하자. 너비를 일정 크기 이하로 제한하면 편하게 볼 수 있다. 같은 비율로 축소해서 넣게 되면 정돈된 느낌의 문서를 만들 수 있다.
입력값을 채우고 캡쳐하자. 대화 상자를 캡쳐할 때는 입력 상자에 값을 입력한 다음 캡쳐하자. 대화 상자 안에 입력값이 중요하기 때문이다.
스크린샷 위에 텍스트를 추가하지 말자. 복잡한 그림에서 특정 부분만 강조할 때, 강조 표시 테두리를 추가하자. 텍스트를 넣어야 한다면, 그림 바깥에 넣자.

✨ 정보를 비교할 때는 표를 활용하자

표를 사용하면 복잡한 정보도 한눈에 확인할 수 있다. 특히 장단점이나 옵션별로 간단한 설명은 가독성을 높일 수 있다. 그러나 표를 만드는 데 시간이 걸리기 때문에 무리하게 사용할 필요는 없다.

✨ 데이터 성격에 맞는 차트를 사용하자

데이터를 비교하거나 변경 추이를 나타낼 때, 관계를 표시할 때 차트를 사용한다. 글로만 되어 있으면 한번에 파악하기 어렵기 때문이다. 효과적으로 내용을 전달하기 위해선 데이터 성격에 맞는 차트를 선택해야 한다. 차트 종류는 아래와 같다.

선형 차트

데이터 점을 연결된 선으로 구성한다. 주가 변동 같은 추이 변화를 나타낼 때 많이 사용한다.

막대형 차트

데이터의 여러 개의 관계를 나타내는 데 주로 사용한다. 비교할 데이터가 많다면 선형보다는 막대형을 사용하면 좋다. 선형은 연속성이 있는 데이터를 표현할 때, 막대형은 연속성이 없는 데이터를 표현할 때 사용하면 효과적이다.

파이형 차트

주로 비교하는 항목이 전체 중 어느 정도, 몇 %를 차지하는지 나타낼 때 사용한다. 주의할 점은 여러 부분으로 많이 나누지 않아야 한다. 6개가 넘어가면 복잡해져서 파악하기 어렵다. 이런 경우에 막대 차트를 사용하는 것이 더 낫다.

✨ 시각 자료를 쓰기 전에 소개부터 하자

다짜고짜 본론부터 시작하면 왜? 라고 생각한다. 시각 자료도 마찬가지다. 왜 넣었는지 미리 알려야 한다. 따라서 설명을 생략하고 캡쳐 이미지만 나열하지 않도록 유의하자.

✨ 시각 자료를 설명하는 캡션을 활용하자

캡션은 삽입된 그림이나 도표, 사진 등의 이해를 돕기 위한 간단한 해설문을 뜻한다. 보통 '그림 + 순차 번호 + 그림 내용'으로 넣는다.
예시) 그림 1-1, 그림 1-2 ...
캡션에 대한 기준은 아래와 같다.
왼쪽 아래가 적당하다.
최대한 그림이 무엇을 나타내는지 간단히 쓰자.
굵게, 배경색을 본문 텍스트와 다르게 지정하자.
그림이 5개 이하라면 캡션을 생략하자.

📌 참고 자료

TOP