[BOOK] 개발자의 글쓰기

[BOOK] 개발자의 글쓰기 – 김철수 지음

부제: “변수 네이밍부터 릴리스 노트, 장애 보고서, 기술 블로그까지, 프로그래머의 글쓰기 고민 끝!”

사내 개발자 필독도서 시리즈 – 2편

개발자에게 가장 중요한 장비는 키보드다. 코딩도 문법에 맞게 키워드을 입력하는 것이다. 그런데 유독 문서화에 약한 것은 왜일까? 연습이 부족한 것도 있겠지만 어떻게 쓰는 것이 좋을지 몰라서 약할 수도 있다. 이 책은 글쓰기의 기본적인 내용을 담고 있고, 특히 개발자가 작성하게될 여러 포멧의 문서에 대해 설명해준다.
요즘 코로나로 비대면 근무가 많아지는 상황에서 글쓰기 능력은 점점 더 중요해지고 있다. 책을 읽어보고, 블로그 등을 통해서 연습을 해보자!

1. 개발자는 프로그램 안에서 글을 쓰거나 개발 완료 후 결과서나 산출물을 주로 쓴다.
2. 기획자나 관리자의 글쓰기에 논리력, 설득력, 실행력이 중요하다면, 개발자의 글쓰기에는 정확성, 간결성, 가독성이 중요하다.
3. 보통 개발자는 글 한 줄 쓰기가 참 어렵다.
4. 문장을 쉽게 쓰려면 간단한 문장 구조로 핵심만 말한 뒤, 필요에 따라 부가 설명을 하면 된다.
5. 사람은 계층이 표현되지 않은 문서를 보면서 체계를 잡아내기가 무척 어렵다.
6. 정확한 단어를 쓰는 것도 중요하지만 그보다 더 중요한 것은 얼마나 일관성있고 개연성 있게 쓰느냐다.
7. 모든 개발자는 자기 코드를 읽는 사람이 주석 없이도 금방 이해하게 코드를 작성하고 싶어 한다.
8. 소통이 잘 되려면 서로가 같은 컨벤션을 지켜야 한다.
9. 약어를 만드는 좋은 방법은 보편성을 기준으로 정하는 것이다.
10. 주석의 악순환에서 벗어나는 가장 좋은 방법은 주석도 코드라고 생각하는 것이다.
11. 서비스와 사용자를 이해하면 에러 메시지 대신에 예방 메시지를 보여줌으로써 에러 발생을 막을 수 있다.
12. 사용자가 에러 메시지를 어떻게 받아들일지는 모두 개발자의 철학에 달렸다.
13. 체인지 로그는 회사의 공식 발표이며, 독자와 직접 소통하는 문건이다.
14. 릴리즈 문서는 단순히 정보를 제공하는 것을 넘어서 고객에게 제공하는 문제 해결 보고서라고 할 수 있다.
15. 정치적 글쓰기는 자신의 처지를 따지거나 상사 눈치를 살펴가면서 얼버무리듯 보고하는 것이 아니다. 정확한 단어와 문장으로 현상과 사실을 있는 그대로 표현하는 것이다.
16. 개발자가 독자에게 서비스 개념을 설명할 때는 범주, 용도, 특징 순으로 쓰는 것이 좋다.
17. 서사에서 의미는 작가가 부여한다. 사건이나 상황 그 자체가 의미 있거나 없는 것이 아니라 작가가 어떤 것에 의미를 두느냐에 따라 글이 달라진다.
18. 거의 모든 문제와 답은 제안요청서에 들어 있다.
19. 제안에는 고객의 문제 인식과 제안사의 문제 해결 능력이 ‘문제’다.
20. 문제해결 과정의 핵심은 문제를 충분히 고민하여 해결 방안을 전략적으로 선택하는 것이다.
21. 기술 블로그를 쓸 때는 독자 수준이 아니라 작성자 수준으로 쓰는 편이 낫다.
22. 글쓰기 기교는 글을 아름답게 만들고 쉽게 읽히게 한다.
23. 좋은 기술 블로그는 개발자의 경험에서 우러나오는 내용을 적절한 글쓰기 기교로 녹아낸 것이다.
24. 저(著)는 직접 경험한 것을 쓴 것이다. 목차만 제대로 잡으면 다른 종류의 글보다 쓰기 쉽다.
25. 술(述)은 어떤 것을 분석해 의미를 풀이하고 해석한 것이다. 술에 해당하는 기술 블로그를 쓸 때는 본래 내용을 바탕으로 자기 생각이나 분석, 해설을 덧붙이는 방식을 쓰는 게 좋다.
26. 편(編)은 산만하고 복잡한 자료를 편집해 질서를 부여한 것이다.
27. 집(輯)은 여러 사람의 견해나 흩어진 자료를 한데 모아 정리하는 것이다. 내용을 많이 쓰는 것이 아니라 핵심만 간결하게 정리한 것이다.
28. 개발자의 글쓰기 원칙이나 수준을 정하기 전에 회사의 글쓰기 문화를 먼저 정의해야 한다.