개발자의 글쓰기

🔖 개발자의 글쓰기

김철수 지음 | 위키북스 | 2019년 10월

✅ 해당 도서를 읽고 영감을 주는 부분 및 학습한 내용을 요약한 기록입니다.

---

[ 프롤로그 ]

개발자가 쓰는 글은 주로 클래스나 함수의 이름, 주석, 에러 메시지, 릴리스 문서, 개발 가이드 등이다. SM 일을 한다면 장애 보고서를 쓰기도 하고 SI 일을 한다면 제안서를 쓰고 프로젝트 완료 후 ERD나 기능 명세서 같은 각종 개발 산출물을 쓴다. 요즘 개발자 중에 블로거가 많아서 개발과 관련한 게시물도 쓴다.

🍀 이런 개발자의 글과 문서는 정확하고 간결하며 가독성이 높아야한다.

• 정확성 : 틀림이 없이 확실한 것을 말한다. 글로 쓰인 대로만 개발하면 버그 없이 실행돼야 한다.

• 간결성 : 글에 군더더기가 없고 간단하고 깔끔한 것을 말한다. 구구절절 설명하는 것이 아니라 핵심만 써야 한다.

• 가독성 : 쉽게 읽히는 것을 말한다. 쉬운 용어를 사용하고 필요하다면 표나 그림으로 잘 정리해야 한다. 문단과 문서 전체에 체계와 위계가 갖추어져야 한다.

---

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

🌿 문장을 구조화하는 법

문장을 만드는 방법이 이렇게 다양하므로 문장을 어떻게 만드느냐에 따라 글을 쓰는 속도가 달라진다. 예를 들어 다음 문장을 보자.

ex) 색상 RGB 값을 각각 사용하기 때문에 입력 데이터는 3차원 벡터다.

• 이 문장의 주어는 '입력 데이터'다. 따라서 주어를 문장의 처음으로 뺄 수 있다.

  ex) 입력 데이터는 색상 RGB 값을 각각 사용하기 때문에 3차원 벡터다.

• 이 문장은 인과관계가 있는 복문이므로 두 문장으로 나눌 수 있다.

  ex) 입력 데이터는 색상 RGB 값을 각각 사용한다. 그래서 입력 데이터는 3차원 벡터다.

• 이제 입력 데이터가 3차원 벡터인 이유를 어떻게 설명할 것인지 결정하면 된다.

  ex) 입력 데이터는 3차원 벡터다.

• 문장을 쉽게 쓰려면 이처럼 간단한 문장 구조로 핵심만 말한 뒤, 필요에 따라 부가 설명을 하면 된다. 이때 첫 문장의 주어를 가져다가 소제목으로 만들면 자연스럽게 문단을 구성할 수 있다.

  ex) [입력데이터] 입력데이터는 3차원 벡터다. 색상 RGB 값을 각각 사용하기 때문이다.

🌿 서술식, 개조식, 도식의 차이

개발자의 생각을 글로 표현하는 데는 크게 세가지 방법이 있다.

• 첫째는 서술식이다.

  • 서술식은 바로 앞의 문장처럼 '~다'로 끝나는 완전한 문장으로 구성된 글을 말한다.
  • 줄거리가 잇는 설명이나 이야기라면 서술식으로 써야 한다.

• 둘째는 개조식이다.

  • 개조식은 신문의 헤드라인을 쓰거나 어떤 사항을 나열할 때 사용한다.
  • 여러 사항이 유사한 패턴으로 반복될 때 사용하면 보기도 좋고 이해하기도 쉽다.
  • 개조식 표현에는 중복과 누락이 있을 수 있다.
  • 서술식에서 강조가 필요한 내용이라면 개조식으로 써야 한다.

• 셋째는 도식이다.

  • 도식은 사물의 구조나 관계, 상태를 그림이나 서식으로 보여주는 것이다.
  • 각 항목이나 사항의 관계를 명확히 규정하고 싶다면 도식으로 써야 한다.

비즈니스 문서에서 위치와 계층은 항상 붙어 다난다. 위치만 있어서도 안되고 계층만 있어서도 안 된다. 글을 쓸 때는 항상 위계가 잘 드러나게 글을 쓰고 표현해야 한다.

---

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

🌿 좋은 이름이 가진 5가지 특징

패키지, 클래스, 모듈, 함수, 변수를 망라해 좋은 이름인지를 확인하는 5가지 기준을 SMART로 정했다.

• easy to Search 검색하기 쉽고
• easy to Mix 조합하기 쉽고
• easy to Agree 수긍하기 쉽고
• easy to Remember 기억하기 쉽고
• easy to Type 입력하기 쉽고

🌿 코드는 의미를, 주석은 의도를

🍀 글은 의미를 전달하는 수단이다. 코드도 마찬가지다.

개발자가 어떤 의도를 전달하는 이유는 다른 개발자를 위한 것이다. 코드를 왜 이렇게 작성했는지 설명하고 뜻밖의 발견을 제시하거나 새로운 아이디어를 보여주거나 어떤 방법이 더 좋은지 알려주는 것은 모든 다른 개발자를 배려하는 마음이다.

---

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

🌿 개발자용 에러 메시지와 사용자용 에러 메시지를 분리하자

개발하다 보면 개발자용 에러 메시지와 사용자용 에러 메시지를 섞어서 쓰곤한다. 보통은 로그를 사용하지만 가끔 알림창을 쓸 때도 있다. 이런 경우를 피하려면 처음부터 개발자용 에러 메시지와 사용자용 에러 메시지를 분리해 작성하는 것이 좋다.

🌿 사용자 에러에 대처하는 메시지

사용자가 개발자의 의도대로 프로그램을 사용해야 하는데, 실제로는 그렇지 않은 경우가 많다.

에러 메시지의 목적은 사용자에게 에러가 났음을 알려주는 것이 아니라 사용자 스스로 에러를 해결하게 하는 것이다. 따라서 사용자 에러 메시지에는 에러의 내용, 에러의 원인, 에러 해결 방법이 포함돼야 한다.

• 에러 내용 : 오류로 인한 문제와 종류
• 에러의 원인 : 오류를 발생시킨 직접적이고 근본적인 원인
• 에러 해결 방법 : 사용자가 오류를 해결할 가장 쉽고 빠른 방법

🌿 서비스를 이해하면 에러를 예방할 수 있다.

모든 개발자는 사용자가 에러 없이 프로그램을 사용하게 만들고 싶어 한다. 하지만 에러가 한 번도 발생하지 않게 프로그램을 온전히 개발할 수 있는 개발자는 없다. 사용자마다 사용법이 제각각이고, 아무리 매뉴얼이나 도움말을 충실히 적어도 사용자가 무시하고 마음대로 사용하기 일쑤다.

🍀 그래서 에러를 줄이려면 개발자도 사용자의 사용방식을 이해해야 한다. 사용자가 어떻게 사용할지를 충분히 이해하고 조사하고 분석해야 에러를 줄일 방법을 찾을 수 있다.

---

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

🌿 체인지 로그의 양과 만족도의 관계

어떤 일을 하고 나서 그 일의 내용을 상사나 고객에게 글로 보고해야할 때가 있다. 이때 글을 지나치게 줄여 쓰면 일을 안 한 것처럼 보인다. 그렇다고 해서 일의 내용을 하나씩 구체적으로 다 쓰면 아무도 읽지 않는다. 체인지 로그가 이런 경우에 해당한다. 간단히 쓰면 한 일이 없어 보이고 자세히 쓰면 아무도 읽지 않아 쓸모가 없다.

🍀 체인지 로그를 적절한 양으로 쓰려면 일단은 체인지 로그를 최대한 많이 써야한다. 그다음에는 일정한 기준으로 선정하고 비슷한 것 끼리 분류한 뒤 문장을 요약하는 기술이 필요하다.

• 1단계 : 선정하기

  • 체인지 로그 중에서 쓸 것과 없앨 것을 구분하는 기준이 필요하다.

• 2단계 : 분류하기

  • 공개할 체인지 로그를 선정했으면 비슷한 체인지 로그끼리 묶어야 한다.
  • 첫 번째 방법은 개발 관점에서 비슷한 작업으로 묶는 방법으로, 독자가 개발자인 경우에 유용하다. 보통 소프트웨어 릴리스 문서에서 사용하는 새로운 기능 추가, 기능 개선, 오류 수정으로 묶을 수 있다.
  • 두번째 방법은 독자가 일반 사용자인 경우에 유용하며, 사용자 관점에서 비슷한 것 끼리 묶는 방법이다.

• 3단계 : 요약하기

  • 체인지 로그를 분류했으면 문장 단위로 요약할 차례다. 여러 가지 요약 방법 중에서 서술식 문장을 개조식 문장으로 바꾸는 방법을 쓰면 내용이 자연스럽게 축약되고 의미는 더 분명해진다.

• 4단계 : 종합하기

  • 상사나 고객이 체인지 로그를 하나씩 뜯어보기 전에 이번 릴리스가 이전과 비교해서 뭐가 다르고 핵심과 컨셉이 무엇인지 한마디로 알려줘야 한다. 그러려면 릴리스 내용 전체를 종합해서 한 문장으로 만들고 그것을 체인지 로그 첫 줄에 적어야 한다.

---

📑 7장 | 기술 블로그 쉽게 쓰고 운영하기

🌿 개발자가 기술 블로그를 잘 못 쓰는 이유

개발자가 기술 블로그를 잘 못 쓰는 이유 중 하나는 블로그에 글을 쓰는 방법이 학생이었을 때 배운 글쓰기 방법과 다르기 때문이다. 우리가 학생이었을 때 배운 글쓰기 방법과 다르기 때문이다. 우리가 학생이었을 때 배운 글쓰기 방법은 주로 논설문이나 설명문을 쓰는 방법이었다.

🍀 필자는 개발자가 블로그에 글을 쓸 때 개발자에게 적합한 방법 세 가지를 제시한다.

• 첫째, 소재 우선 글쓰기
• 둘째, 자기 수준 글쓰기
• 셋째, 재미있는 글쓰기

🌿 주제 의식을 버리고 소재 의식으로 쓰자

소재 우선 글쓰기는 주제 의식이 아니라 소재 의식을 갖고 쓰는 것이다. 주제 의식이 민족이나 권선징악, 자존감이나 자본주의 같은 추상적 가치를 기반으로 한다면 소재 의식은 특정한 대상이나 상황에 대한 자기만의 관점이나 생각이나 해결 방안을 뜻한다.

ex) 우아한 형제들 기술 블로그에 올라온 글 중에 "데이터베이스의 자동증가 값을 기본키로 사용할 수 없을 때는?"이 있다.

🌿 독자 수준이 아니라 자기 수준으로 쓰자

글쓰기 전문가들은 다른 글을 쓸 때 초등학생도 이해할 수 있도록 쉽게 풀어서 쓰라고 한다. 하지만 직장에서 하는 일을 초등학생이 이해할 수 있게 풀어서 글을 쓰는 사람은 없다.

개발자가 기술 블로그를 쓸 때는 독자를 생각해서 어려운 용어를 일부러 해석해 풀어쓰거나 쉬운 용어로 바꿀 필요가 없다. 원래 사용하는 용어로 그냥 표기하되 필요하다면 용어를 정의한 위키피디아 페이지나 세부 내용을 볼 수 있는 사이트나 문건을 링크로 걸어두면 된다.

🍀 기술 블로그란 것은 결국 실력이 비슷한 독자를 위한 것이다. 독자에게 다 설명하느 것이 아니라 핵심 내용만 쓰고 나머지는 독자가 공부할 수 있게 길만 터놓는 것이 현명한 방법이다. 그래야 개발자도 자기가 쓰려는 글의 본질에 집중할 수 있다.

🌿 재미있게 글을 쓰자

논문이나 기술 매뉴얼, 사용 설명서를 쓸 때는 자신의 경험을 녹여내거나 글의 기교를 부릴 여지가 별로 없다. 이런 글은 정확하고 군더더기가 없이 깔끔하지만, 글 쓰는 재미나 읽는 재미가 별로 없다.

글쓰기 기교는 글을 아름답게 만들고 쉽게 읽히게 한다. 기교를 부리다 보면 글쓰기가 재미있고 글도 재미있어진다. 글에 재미가 있으면 독자가 활발히 반응하고 독자의 반응이 활발하면 블로거는 글을 계속 쓸 동력을 얻는다. 글쓰기 기교는 이렇게 선순환을 만든다.

🍀 API 레퍼런스가 위키피디아처럼 인공지능 컴퓨터가 담담하게 쓴 것 같다면 기술 블로그는 그 글을 쓴 사람의 경험을 독자가 온몸으로 공감하고 끄덕이게 만들어야 한다.

🌿 기술 블로그의 4종류, 저, 술, 편, 집

• 저 著 : 직접 경험하고 실헌한 과정이나 결과
  - ex) 개발기, 도입기, 적용기

• 술 述 : 어떤 것을 분석하며 의미를 풀이하고 해석한 것
  - ex) 기술 소개, 용어 분석, 에러 해결 방법 등

• 편 編 : 산만하고 복잡한 자료를 편집해 질서를 부여한 것
  - ex) 프로그램 설지/설정 방법, 튜토리얼, 세미나 후기, 책 리뷰

• 집 輯 : 여러 사람의 견해나 흩어진 자료를 한데 모아 정리한 것
  - ex) 명령어 모음, 팁, OO가지 규칙

[에필로그]

개발자 혼자 공부해서는 실력이 나아지기가 쉽지 않다. 회사가 개발자에게 글쓰기를 체계적으로 교육해야 개발자의 글쓰기 수준이 높아진다. 그러면 버그의 비용이 줄어들고, 생산성과 고객 만족도가 높아진다. 회사의 교육 수준이 개발자의 개발수준인 셈이다.