[개발자의 글쓰기] 5장. 설명, 묘사, 논증, 서사로 개발 가이드 쓰기

이 글은 "개발자의 글쓰기"를 읽고 좋은 구절들을 기록하거나 느낀 점을 기록하는 글입니다.

개발자의 글쓰기

5장은 설명하는 글을 작성할 때 다양한 방법에 대해 알려준다.

 

1. 서비스 개념을 범주, 용도, 특징으로 설명하자

개발자가 독자에게 서비스 개념을 설명할 때는 범주, 용도, 특징 순으로 쓰는 것이 좋다.

 

범주는 여러 경쟁사가 사용하는 보편적인 서비스 범주를 따라 하면 좋다. 

범주는 서비스의 정체성과 검색어와도 연관이 있기 때문에 신중하게 정해야 한다.

 

용도는 독자가 이 서비스를 이용하는 이유다. 

서비스의 핵심 기능을 쓰면 용도를 기술할 수 있다.

 

특징은 차별화하는 내용을 적는다. 차별화는 서비스의 장점과 강점이다.

장점은 자기 기준에서 잘하는 것이고, 강점은 경쟁 서비스보다 나은 점이다.

 

2. 정확히 이해하도록 그림과 글로 묘사하자

글에 묘사를 더하면 이해가 빠르다.

• [시각 묘사] 새하얀 눈이 내린 나무
• [청각 묘사] 바람에 나뭇잎이 흔들리고 있는 나무
• [후각 묘사] 상쾌한 향기를 내뿜는 나무
• [미각 묘사] 상큼할 것 같은 열매가 열린 나무
• [촉각 묘사] 찔리면 아플 정도의 뾰족한 나뭇잎을 가진 나무

하지만 언어로만 묘사를 하는 것에는 한계가 있다. 그래서 그림을 추가해주면 더욱 좋다.

글 아래 그림을 그리거나 사진을 추가해주면 더 빨리 이해할 수 있을 것이다.

 

글과 그림이 같이 있을 때 사용하는 용어를 같게 해주어야 한다.

같은 것을 다르게 표현하면 독자를 헷갈리기 시작한다.

 

3. 독자의 수준 대신 기술의 범용성을 기준으로 쓰자

서사는 사실을 있는 그대로 순서대로 적는 것이지만 단순한 사건이나 상황을 무조건 기술하는 것은 아니다.

독자의 수준에 맞춰서 작성해야 하는데 개발 문서는 독자의 폭이 매우 넓다. 어떤 실력을 가졌는지 모르기 때문이다.

이해하기 쉽게 길게 쓰다간 내용이 길어지고 수준을 높여 짧게 쓰면 이해하기가 어렵다.

 

그래서 기술의 범용성을 기준으로 하는 것이다.

기술이 처음 나왔을 때는 초등학생이나 어른이나 똑같거나 비슷한 수준일 것이다. 하나하나 세심히 설명해주어야 한다.

기술이 등장하고 오랜 시간이 지나면 지식이 상향 평준화되기 때문에 좀 더 간단하게 설명을 해도 충분할 것이다.