개발자의 글쓰기 - 김철수

예전에 읽었던 책인데, 업무상 되돌아볼 일이 있어 2024년 9월에 다시 읽은 책.

 

내가 읽어본 개발 글쓰기를 다룬 책 중엔 가장 실용적으로 잘 썼다고 생각하는 책이다. 개발자를 대상으로 하는 글쓰기 기초 교육부터 시작하여 변수 이름 짓기, 주석 잘 쓰기, 에러 메시지 쓰기 등 개발 과정에서 필요한 부분도 안내한다. 그래서 코딩룰을 잡고자 하는 개발 조직이나 신입 개발자에게 교육 자료로 유용해 보인다. 또한 체인지 로그, 릴리스 노트, 장애 보고서, 개발 가이드 등 업무상 써야 하는 글 종류 및 쓰는 방법에 대해 잘 소개했다. 심지어 SI 제안서 쓰는 법도 있는데 이건 내 업무와 관련이 없어 자세히 읽은 적은 없다.

 

이 책의 가장 좋은 점은 0 혹은 1에 익숙한 개발자에게 뜬구름 잡는 소리가 없다. 개발자가 읽기 좋게 A이면 B이다 식으로 설명한다. A이면 B일 수도 있고 C일 수도 있다 식으로 모호한 표현은 없다는 뜻이다.

제목은 '개발자'의 글쓰기지만 PM에게도 꽤 유용할 것으로 보이고 기술 리더, 주니어급 테크니컬 라이터가 읽어도 좋을 글이다.

 

이 책에 대해 위에서 언급한 것 이상의 자세한 설명은 필요하지 않다고 생각한다. 필요한 경우 목차 보고 발췌독을 하면 되는 실용 서적인 관계로 세세한 감상은 생략하겠다.

 

---

 

개인적으로 유용했던 부분 메모

p35 / 다음 한 문장만 기억하면 된다.

"조사, 순서, 숫자, 하다, 기호만 붙이고 나머지는 띄어 쓴다."

 

p45 / 이미 굳어진 외래어는 관용을 존중하되, 그 범위와 용례는 따로 정한다.

 

p97 / 사용자가 잘못해서 에러 메시지를 만날 가능성이 있다면 에러 페이지에 죄송하다는 말을 넣을 필요 없다

 

p138 / 깃허브의 공동창업자인 톰 프레스턴 베르너가 정한 Semantic Versioning

버전은 XYZ의 형태로 한다. X를 Major, Y를 Minor, Z를 Patch로 간편하게 이해해도 좋다.

 

p120 / 체인지 로그: 상사나 고객에게 변경사항에 대한 보고

p139 / 릴리스 노트: 고객에게 제공하는 문제 해결 보고서

 

p143 / 개발자가 주로 쓰고 완성하는 릴리스 노트에는 개발자의 법적 책임을 줄일 수 있는 내용, 즉 면책 조항을 꼭 적는 것이 좋다.

p144 / 릴리스 노트를 통해 거래 회사 개발자에게 어떤 행동을 유도할 때는 그 행동이 필수인지, 권장인지, 선택인지를 명확히 알려줘야 한다.

 

p148 / 장애 보고서 글쓰기 기법

1. 질문에 대답하는 신속한 글쓰기
2. 원인과 이유를 찾는 분석적 글쓰기
3. 상사를 고려하는 비즈니스 관점의 글쓰기
4. 원하는 것을 얻는 정치적 글쓰기

p162 / 정치적 글쓰기는 자신의 처지를 따지거나 상사 눈치를 살펴 가면서 얼버무리듯 보고하는 것이 아니다. 정확한 단어와 문장으로 현상과 사실을 있는 그대로 표현하는 것이다.

 

p171 / 장점은 자기 기준에서 잘하는 것이고, 강점은 경쟁 서비스와 비교해서 나은 것이다.

 

p187 / 개발문서에서 공손한 표현은 좋지 않다. 공손하게 말하는 순간 독자가 오해할 소지가 있다. (...) 다음과 같이 바꾸자.

•   ~하십시오.
•   ~하지 마십시오.

세상에 어떤 일이든 100% 확신할 수는 없다. 하지만 개발문서는 독자에게 여지를 줘서는 안 된다.