<유영경님> 개발자를 위한 글쓰기 가이드

기술블로그 포스팅 및 서면 업무 요청/문의에 유용한 책이다. 목차만 잘 기억해둬도, 글의 전달력을 높일 수 있겠다는 생각이 들었다. 책의 문장도 간결하여, 머리에 쏙쏙 들어온다. 

 

✍🏻 밑줄 그으며 책읽기

1. 요점만 말하기: 역피라미드 방식

2. 제목에 요점을 담기

예시

ID으로 주문 검색하기 

3. 문장 하나에는 주제를 하나만 쓰기

4. 객관적인 근거 대기

예시

1. 레디스 캐시를 사용하면 응답시간이 200ms 감소한다. 
2. ISMS 인증을 받기 전까지 보안 시스템을 바라보는 시선이 좋지 않았다. 

5.  전문용어는 독자에 맞게 사용하기 

예시

1. 사용자 입력 값이 잘못되었을 때 나타나는 오류 코드입니다.
2. 서비스 기술 문의 담당자는 백엔드팀 소속입니다.

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

웹 문서인 경우, 용어집 페이지를 제공할 수도 있다.

예시

토스페이먼츠 용어집 사례 

 

7. 용어는 일관되게 사용한다.

용어를 섞어쓰지 않는다.

예시

스토리지 / 저장소
레이턴시 / 대기시간

8. 쉽게 쓴다.

한자어, 긴 문장을 사용하지 않는다. 

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

어떤 맥락에서 그림이 나온건지 알 수 있다. 

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

검토 방법

• 소리내어 읽기
• 작성한지 24시간이 지난 후, 시간을 두고 다시 읽기 
• 온라인 문서라면 인쇄해서 읽기 

체크리스트

• 내용에 맞는 제목을 달았는가?
• 목차가 올바른가?
• 용어를 일관되게 사용했는가?
• 어려운 용어는 없는가?
• 필요한 정보가 모두 있는가?
• 불필요한 정보가 있는가?
• 목차가 내용을 찾기 쉬운가?
• 단락을 적절히 나누었는가?
• 중복이 없는가?
• 객관적인 근거가 있는가?
• 출처가 명확한가?
• 외국어나 한자어가 많은가?
• 피동태가 많은가?
• 그림이 적절하게 배치되었는가?
• 표를 적절하게 사용했는가? 

 

11. 맥락에 맞는 단어를 사용한다.

• 🙅🏻‍♀️ 푸시 발송을 보낼 수 있습니다.
• 🙆🏻‍♀️ 푸시 알림을 보낼 수 있습니다. 

 

12. 은어는 형식적인 표현으로 교체한다. 

• 🙅🏻‍♀️ 엑박이 뜬다. 
• 🙆🏻‍♀️ 그림이 제대로 나타나지 않는다. 

 

13. 대명사는 일반명사로 교체한다.

• 🙅🏻‍♀️ API 가이드는 여기를 확인하세요. 
• 🙆🏻‍♀️ 토스페이먼츠 개발자센터 가이드를 확인하세요.

 

14. 단정적인 어조로 확신 있게 쓴다. 

• 🙅🏻‍♀️ ~좋을 듯 합니다.
• 🙆🏻‍♀️ ~을 사용합니다.

 

15. 글꼬리를 뚜렷하게 쓴다. 

 

16. 주어와 서술어를 일치시킨다. 

 

17. 문장은 짧게 줄인다. 

• 군더더기 + 중복되는 표현은 제거한다. 

18. 능동태로 작성한다. 

• 🙅🏻‍♀️ 대량의 API 호출에 의해 부하가 증가했다.
• 🙆🏻‍♀️ 대량의 API 호출이 부하를 증가시켰다. 

19. '무엇은 ~무엇이다' 형식으로 쓰지 않는다. 

20. 🙅🏻‍♀️ ~해주다 🙆🏻‍♀️ ~하다

21. 조사를 덜어내기 

을/를/의를 줄여보자.

 

🧠 응용하기 

고민이 될 때는 GPT에게 글을 다듬어 달라고 요청하자.