[리뷰] 개발자의 글쓰기

개발을 하면서 생각보다 많은 글쓰기가 필요하다. 개발자의 대부분이 가장 많이 고민하는 부분이 변수 네이밍이라고 한다. 나도 변수명 짓는 것이 굉장히 어렵다. 쉽게 지어질 수 있는 변수명이 생각나면 기쁠정도로! 그렇기에 이 책을 선택하게 되었다. 

예시로 보여주는 글들이 깔끔하여 참고하기에 아주 적합하다고 느꼈다. 사용자들의 요건을 정리하여 반영하는 과정에서 메일을 작성한다. 주로 화면별로 반영된 목록을 정리하였는데, 사용자가 받아들이기 편한 방법은 무엇일지 고민하게 되는 듯하다.

다만, 책에서 변수명을 쉽게 짓는 방법에 대해서도 말하지만, 변수명이 너무 길어지는 게 아닌가 싶은 생각이 들었다. 의미를 부여하기 위해서는 그만큼의 단어를 포함해야하는데, 그렇게되면 또 변수명이 엄청 길어질 것이다. 이것을 딜레마라고 봐야할까?

글을 많이 써보고 기교도 부릴 수 있도록 노력해봐야겠다~

---

1장. 개발자가 알아야할 글쓰기 기본

<글의 진술방식마다 사용되는 말머리 기호>

• 문장을 구조화하는 법, 문장의 핵심을 먼저 말하고 추가설명이 필요한 경우 뒤에 붙여서 설명한다.
• 비즈니스 문서에서 문단과 문단 사이에 위계가 필요하다. 계층은 굵기, 모양, 및줄, 줄 간 거리 등으로 표현한다.
• 띄어쓰기는 “조사, 순서, 숫자, 하다, 기호만 붙이고 나머지는 띄어쓴다.”만 기억하자.

2장. 개발 시간을 줄여주는 이름짓기와 주석쓰기

개발자들이 가장 고민하는 1순위가 바로 네이밍!

• https://brunch.co.kr/@goodvc78/12 에서 몇가지 중요한 네이밍 규칙을 데이터로 증명했다.
• 이름을 잘 지으면 주석이 필요없다. 주석없이 변수명만으로 역할을 파악할 수 있어야한다.
• 코드는 의미를, 주석은 의도를 나타낸다. 주석은 이유를 알려준다거나 새롭게 발견한 것 등등 다른 개발자에게 참고할 수 있는 생각이나 의견을 표현한다.
• 가이드 문서를 보면 반복해서 나오는 코드의 주석도 함께 반복된다. 글을 읽는 사람이 처음부터 차례대로 보지 않을 수 있다. 따라서 주석도 함께 반복되게 된다.

---

3장. 사용자와 소통하는 에러 메시지 쓰기

• 사용자 에러 메시지에는 에러의 내용, 에러의 원인, 에러 해결 방법이 포함돼야 한다.
• 버튼에 구체적인 행동을 적는 것도 좋은 방법이다.
• 에러가 발생하기 않게끔 미리 예방을 하자(ex, 예약시 이전 날짜는 클릭하지 못함)

4장. 독자 관점에서 릴리스 문서와 장애 보고서 쓰기

• 체인지 로그를 적절한 양으로 쓰려면, 일정한 기준으로 선정하고 비슷한 것 끼리 분류한 뒤 문장을 요약하는 기술이 필요하다.
• 선정하기 → 분류하기 → 요약하기 → 종합하기
• https://semver.org/lang/ko/ 를 참고. 버전 올리는 가이드
• 질문을 통한 장애 보고서 항목
  • “뭐야, 뭐야? 무슨일이야?” ⇒ 장애 내용
  • “그래서 어떻게 됐어?” ⇒ 장애 영향
  • “왜 그렇게 됐어?” ⇒ 장애 원인
  • “넌 어떻게 했는데?” ⇒ 조치 사항
  • “그럼 이제 장애는 해결된 거야?” ⇒ 조치 결과
  • “누가 잘못한거야?” ⇒ 핵심 원인
  • “그럼 이제 어떻게 할 거야?” ⇒ 향후 대책

<장애 재발 가능성에 대해 말할 때>

---

5장. 설명, 묘사, 논증, 서사로 개발 가이드 쓰기

• 경쟁사보다 전반적으로 발전한 서비스라면 “A는 보다 발전된 크라우드 펀딩 서비스입니다” 라고 차이를 돋보이게 할 수 있다.
• 그림을 글과 함께 제공하는 경우 그림과 글에서 사용하는 용어를 일치시켜야 혼동을 줄일 수 있다.

6장. 수주를 돕는 SI 제안서 쓰기

고객의 요구사항을 분석하지 말고 제안하라. 고객은 자기가 원하는 것이 정확히 모르기 때문에 외주 용역을 주는 것이다. 요구사항을 받아서 개발을 하는 것이 아니라 요구사항을 고객에게 제시해서 선택할 수 있게끔 해야한다.

7장. 기술 블로그를 쉽게 쓰는 방법 3가지

1. 주제 의식을 버리고 소재 의식으로 쓰자. 특정한 대상이나 상황에 대한 자기만의 관점이나 생각, 해결방안을 말한다.
2. 독자 수준이 아니라 자기 수준으로 쓰자. 기술 블로그란 것은 결국 실력이 비슷한 독자를 위한 것이다. 다 설명하는 것이 아니라 방향성만 제시하는 것이 좋은 방법이다.
3. 재미있게 글을 쓰자. 글쓰기 기교는 글을 아름답게 만들고 쉽게 읽히게 한다.