김철수의 책 ‘개발자의 글쓰기’를 읽고.

협업과 소통을 위해 글은 매우 강력한 수단이다. 개발자와의 협업이 어려운 이유 중 하나는 개발자가 보편적인 말과 글로 자신의 생각과 지식을 이야기하는 걸 어려워하기 때문이라 생각한다. 아니, 굳이 보편적인 말과 글이 아니더라도 자신의 생각과 의도에 맞는 표현을 하는 걸 어려워하는 게 더 맞겠다. 사실 비단 개발자로 국한될 일이 아니라 세대를 걸쳐 생겨나는 현상이라 할 수도 있겠다.

좋은 개발자는 글도 잘써야 한다고 생각한다. 코딩할 때 내 개인적인 가치관 중 하나는

다. 한국어를 개발 언어로만 바꾸고, 언어의 틈새에 있는 문맥을 같이 꺼내서 표현할 뿐이다. 우리가 글을 읽을 때 자연스럽고 당연하다고 생각하는 곳을 향해 흐르는 흐름이 있듯 코드도 개발자가 예상한 곳에 예상한 코드가 있어야 한다. 이걸 논리라고 한다. 논리가 겸비된 글이 사람들을 이해시키기 쉬운 것처럼 코드도 논리가 겸비되어야 이해하기 쉽다.

그 외에도 개발자는 코드 외에도 글을 써야할 일이 꽤 있다. 업무 정리, 배포내역, 장애 보고서, 작업기 등등… 특히 대기업의 기술 블로그에 올라오는 글은 테크니컬 라이터의 첨삭을 거쳐서 올라온다고 하는데 무척 대단한 직업이라고 생각한다.

책

는 부제로 설명을 잘 해주고 있는 것 같다.

이라는 부제를 달고 있는데 1장에서 7장에 이르기까지 각 챕터에서 저자의 경험을 바탕으로 글쓰기 방법을 알려준다.

내가 이 책을 알게 되고 읽게 된 계기는 7장의 기술 블로그 장에서 저, 술, 편, 집의 4가지 종류가 있다는 이야기다. 책을 읽기 전에 어디선가 우연히 접했고, 이는 뇌리에 남아 weezip 블로그의 토대가 되었다. 저술편집을 각 write, explain, edit, zip 단어로 치환한 후 조합했다. 또한 책에서 구분한 기준에 대해서 동일하게 생각하지는 않지만 전체적인 구분법을 보고 내 나름대로 기준을 만들어 그룹화하여 분류한 것이 weezip 블로그의 4가지 카테고리이다.

1장의 내용은 글쓰기의 가장 기본인 단락을 구성하고 띄어쓰기 하는 방법에 대해 저자만의 간단한 팁을 알려준다. 개발자의 시선에 맞춰진 쉬운 설명이라 글의 기본에 대해 입문하기에 좋을 듯 싶다. 시작이 아주 좋다.

2장의 내용은 네이밍과 주석 쓰기 등 코딩에 대한 내용이다. Clean Code에서 읽은 내용과도 흡사한 게 많았는데, 책을 읽으며 함께 떠올린 자주쓰는 동사 비교에 대해서는 Chat-GPT를 통해 따로 비교해서 정리해보기도 했다. 아직 원칙이라고 할 것 까지는 없지만, 설득력 있는 문법의 스타일을 만들어 나가는 중이다.

3장의 내용은 사용자와 소통하기 위한 에러 메시지를 쓰기 위한 방법이다. 서비스 운영에서 인지하고 있는 에러와 예기치 않은 에러들은 발생할 수밖에 없고, 이를 적절한 메시지와 함께 다음 사용자 행동을 유도해야 사용자의 서비스 경험을 해치지 않을 수 있다. 개발하는 도중에 에러메시지까지 고민하기란 쉽지 않은 일이고, 어떤 에러 메시지가 좋은 메시지인가 고민해본 적도 있다.

4장의 내용은 독자의 관점에서 릴리스 문서와 장애 보고서를 쓰는 방법이다. 중간에 Semantic Versioning에 대한 이야기도 나오는데 서비스를 운영하며 버전 관리에 대해 알아본 적도 있었다. 사용자에게 보여지진 않더라도 Github 또는 Gitlab에서 릴리즈 버전을 만들며 작성하는 노트 하나하나가 다른 개발자가 읽을 수 있는 릴리스 문서라고 생각한다. 크리티컬한 이슈가 발생할 경우 이를 분석한 후 유관자들에게 공유하는 것도 개발자가 아니면 할 수 없는 일이다. 누가 개발자 대신 기술적 문제에 대한 설명을 해주겠는가? 단순 코더가 아니라 서비스를 운영하는 입장에서 필수 불가결한 작업이라고 생각되지만 생각보다 이를 접할 수 있는 곳이 없다. 이 책에서 다뤄준 내용만 대충 살짝 알고 있어도 추후 이런 일이 필요해질 때 좀 더 당당하게 대응할 수 있을 것 같다.

5장의 내용은 설명, 묘사, 논증, 서사로 개발 가이드를 쓰는 방법이다. 이는 외부 불특정 다수를 상대로 API를 배포할 때 필요할 수도 있고, 내부 동료 개발자에게 가이드를 줄 때 필요할 수도 있다. 다만 아직까지 가이드 문서를 진지하게 작성할 일은 없었다. 하지만 추후 사이드 프로젝트를 공개할 때 이 내용들이 도움이 될 것 같다.

6장의 내용은 SI 제안서를 쓰는 방법이다. 모든 챕터 중에 이 내용이 제일 나와는 거리가 멀었다. SI 회사에서 일하는 시니어 개발자에게는 무척이나 도움되는 내용이겠지만, 내 SI 경험은 주니어 시절의 1년이 전부이다. 그 때는 그냥 회사에서 가라는 곳 가서 하라는 프로젝트 하는 게 다였다.

7장의 내용은 기술 블로그를 쉽게 쓰고 운영하는 방법이다. 3번 째 블로그 병이 재발했을 때 weezip을 만들어 운영을 시작한 처지로 7장의 내용은 지금의 내게 제일 필요한 내용이었다. 저자가 정리한 저, 술, 편, 집에 대한 내용대로 분류해 볼 때 다소 내 기준과는 맞지 않는 부분이 있었다. 하지만 ‘주제가 아닌 소재로 작성하라는 것’, ‘모든 독자의 수준을 생각하지 말고 내 수준으로 작성할 것’ 등 글을 써내릴 때 공감가는 내용들도 있었다. 예전의 내가 실패했던 이유 중 하나가 너무 세세하게 쓰려고 했던 게 있었다. 물론 그러면서 배우는 것도 있지만, 글 하나를 발행하는 데 리소스가 너무 많이 들고 투입 대비 아웃풋의 결과도 그렇게 좋지 못하니 쉽게 지쳐갔던 것 같다. 중요한 건 내가 꾸준할 수 있는 정도의 리소스로 운영해야 한다는 것이다. 다른 무엇보다 꾸준함의 힘을 믿어야한다.

개발자의 스킬에는 기술적 측면도 물론 중요하지만 커뮤니케이션 측면도 굉장히 중요하다고 생각한다. 우리는 혼자 일하는 게 아니라 협업하기 때문이다. 기획, 디자인, 마케팅 등 다양한 직군의 사람들과 함께 서비스를 만들어 나가는 사람들이기 때문이다. 서로의 언어를 이해하고 같은 목표를 향해 얼라인을 맞추기 위해서는 커뮤니케이션 스킬이 매우 중요하다. 글은 그 중 강력한 수단이다. 글을 작성하는 데 있어 두려움이 없어지고, 코드 또한 좋은 글과 같이 작성되어지길 바란다.