학교 전공 수업 중에 "과학과 기술 글쓰기"라는 글쓰기 수업이 있었다.
글쓰기를 좋아하지 않아 이과를 선택했던 나에게 또다시 글쓰기를 해야 한다는 사실은 달갑지 않은 소식이었다.
수업을 나름 열심히 들었지만 성적이 좋지 않았고, 결국 재이수를 하게 되었다.
그 후로 글쓰기는 앞으로 인생에 없을거라 생각했는데, 남들 다 하는 기술 블로그를 하게 되면서 글쓰기 능력을 기를 필요가 있었다.
회사에 출근한 어느 날, 동기가 개발자의 글쓰기라는 책을 가지고 있길래 이걸 보고 기술 블로그를 좀 더 체계적으로 써보자! 하는 마음으로 훔쳐가듯 빌려왔다.
책을 읽고 나서 가장 충격받았던 사실은 개발자에게 글쓰기는 숨 쉬는 것과 같다는 것이었다.
코드를 작성하는 것도 글쓰기, 코드 리뷰도 글쓰기, 주석, 제안서, 릴리즈 노트, 장애 보고서 모두가 글쓰기다.
내 생각을 다른 사람이 한 눈에 알아볼 수 있도록 코드, 주석, 제안서, 보고서 등으로 잘 풀어내야 한다.
이 책에서는 쉽게 이해할 수 있게 예제를 들어가며 글쓰기 방법을 소개하고 있다.
그중에서도 중요하다고 생각하는 내용만 소개해보고자 한다.
네이밍
비슷한 뜻을 가진 단어도 자세히 살펴보면 그 의미가 다르다. 또, 당연하게도 각각의 단어는 반대되는 뜻을 가진 단어가 존재한다.
알맞은 의미를 가진 단어를 적절히 선택해서 사용하자.
이때 주의해야 할 점은, 정확한 단어의 사용도 중요하지만 일관성 있는 단어를 사용해야 한다는 것이다.
네이밍은 단어를 창조하는 것이 아니라 규칙을 지키며 기존 단어를 조합하는 과정이다.
같이 일하는 사람들끼리는 컨벤션 규칙을 정하는 것이 가독성과 소통에 유리하다.
좋은 이름을 확인하는 기준인 SMART를 기억하자.
- easy to Search: 검색하기 쉽게
- easy to Mix: 조합하기 쉽게
- easy to Agree: 수긍하기 쉽게
- easy to Remember: 기억하기 쉽게
- easy to Type: 입력하기 쉽게
주석
좋은 코드에는 주석이 없다. 가능하다면 주석을 사용하지 않도록 네이밍을 잘하도록 하자.
잘못된 주석을 남길 경우, 혼동을 줄 수 있다. 주석도 코드처럼 중요하게 생각하고 다루자.
기술 블로그
주제 의식을 버리고 소재 의식으로 쓰자
소재 의식이란, 특정 상황을 자기만의 관점이나 생각으로 쓰는 것을 의미한다.
그러한 상황을 맞닥뜨릴 때부터 해결할 때까지를 정리해서 서술하자.
독자 수준이 아니라 자기 수준으로 쓰자
글을 읽는 모든 독자의 지식 수준은 같을 수 없다. 모든 독자를 이해시키기 위해 글을 작성한다면 글이 너무 길어질 것이다.
나는 알지만 독자가 이해하기 힘든 정보라는 생각이 든다면 직접 설명하기보다는 다른 사람이 작성한 글의 링크를 걸자.
기술 블로그는 실력이 비슷한 독자를 위한 것이다.
기술 블로그의 종류
저
직접 경험하고 실험한 과정이나 결과로 개발기, 도입기, 적용기 등을 의미한다.
목차를 잘 설정하면 쉽게 글을 작성할 수 있다.
술
어떤 것을 분석해 의미를 풀이하고 해석한 것으로 기술 소개, 용어 분석, 에러 해결 방법 등을 의미한다.
본래 내용을 바탕으로 내 생각이나 분석, 해설을 덧붙이는 방식으로 작성한다.
편
산만하고 복잡한 자료를 편집해 질서를 부여한 것으로 환경세팅, 튜토리얼, 책 리뷰 등을 의미한다.
시간 순서로 일어난 일이나 해야 할 일을 작성한다. 글 작성이 어렵다면 구조를 생각하지 말고 쭉 나열한 뒤 요약하는 방식으로 작성해 보자.
집
여러 사람의 견해나 흩어진 자료를 한데 모아 정리한 것으로 명령어 모음, 팁, 규칙 등을 의미한다.
핵심만 간결하게 모아서 정리하는 방식으로 작성한다.
이외에도 책에서는 앞서 얘기했던 것처럼 제안서, 릴리즈 노트, 장애 보고서 등 다양한 글을 작성할 때 어떻게 하면 좋을지에 대한 내용도 소개되어 있다.
누구나 부담 없이 읽을 수 있을 정도로 쉽게 작성되어 있으니 글쓰기에 관심 있는 개발자라면 꼭 한 번 읽어보는 것을 추천한다.
G마켓-개발자의 글쓰기 : 변수 네이밍부터 릴리...
16,200원
item.gmarket.co.kr