개발자의 글쓰기

💌 개발자로써 글을 잘 쓰고 싶다.

기술 블로그를 운영하려고 애쓰고, 끊임없이 공부하고, 습득한 지식을 공유하고.. 계속해서 책을 지르고.. 나만의 것을 꾸준히 쌓아가고 싶은 욕구가 큰 것 같다. 그런데 글로써 정리하는 게 참 어렵다. 그래서 글을 잘 쓰고 싶어서 이 책을 읽었다. 많은 부분들에서 글 쓰기에 도움이 되었으며, 앞으로 글을 쓸 때 두고두고 열어볼 것 같은 책이다. 글쓰기에 대한 고민을 하고 있다면 추천하겠다. 분명 도움이 될 것이다. 본인은 이 책의 구성요소 중에서 가장 읽고 싶었던, 기술 블로그 관련 부분만 정리를 해둘까 한다.

아래의 내용은 책에서 해당 부분에 대해 발췌하여 정리한 것이다.

🎈 기술 블로그를 쉽게 쓰는 방법 3가지

우리는 이제껏 글을 써올 때, 항상 목적이 있었다. 그러한 목적을 달성하기 위해선 대상과 주제가 명확해야 하고, 근거가 분명해야 했다. 하지만 기술 블로그에 쓰는 글은 성질이 다르다. 마치 수필과 같은 느낌이라고 생각하고 마음을 편하게 가져야 한다. 가령 예를 들면, 개발기와 같은 것이 있다. 그냥 스스로의 이야기를 쓰는 것이다.

첫째, 주제 의식을 버리고 소재 의식으로 쓰자

소재 우선 글쓰기는 주제 의식이 아니라 소재 의식을 갖고 쓰는 것이다. 소재 의식은 특정한 대상이나 상황에 대한 자기만의 관점이나 생각이나 해결 방안을 뜻한다.

소재 의식은 독자와 상관없이 대상이나 상황에 맞닥뜨렸을 때부터 그 대상이나 상황에서 벗어날 때까지 겪은 일을 담담하게 정리해서 얘기할 뿐이다.

이런 점에서 기술 블로그는 일상을 다룬 수필이나 에피소드와 비슷하다. 수필을 쓰는 사람은 그저 일어난 이야기를 할 뿐이다.

둘째, 독자 수준이 아니라 자기 수준으로 쓰자

직장에서 하는 일을 초등학생도 이해할 수 있도록 쉽게 풀어서 쓰는 것은 사실상 불가능하다. 비유를 들어서 설명하곤 하지만, 이는 단지 어떤 것의 원리를 간접적으로 이해한 것에 불과하다.

기술 블로그를 독자 수준에 맞춰 쉽게 쓰는 것은 굉장히 어렵다. 그렇다고 무작정 쉽게 쓴다고 하여 그 글을 읽는 독자의 활용도가 높아지는 것도 아니다. 그러니 기술 블로그를 쓸 때는 독자 수준이 아니라 작성자 수준으로 쓰는 편이 낫다.

개발자가 어려운 용어를 쓴 것이 문제가 아니라, 독자가 그 용어를 알지 못한 채 글을 읽거나 글을 읽으면서 그 용어를 이해할 능력이 안 되는 상황이 문제다. 용어에 대한 해설을 주르륵 늘어놓는 대신, 해당 용어에 대한 설명이 담긴 링크를 건네주는 것이 낫다. 해설을 늘어놓다보면 정작 할 말을 못 하게 된다.

즉, 개발자가 기술 블로그를 쓸 때는 독자를 생각해서 어려운 용어를 일부러 해석해 풀어쓰거나 쉬운 용어로 바꿀 필요가 없다. 필요하다면 링크를 건네주면 된다.

셋째, 재미있게 글을 쓰자

좋은 기술 블로그는 개발자의 경험에서 우러나오는 내용을 적절한 글쓰기 기교로 녹여낸 것이다. 재미가 없다면 잘 읽히지 않고, 그러다보면 스스로도 흥미를 잃고 만다. 나무위키가 위키피디아보다 읽는 재미가 있다. 위키피디아에는 없는 경험과 기교가 나무위키에는 있기 때문이다.

🎢 글의 종류별로 목차 잡는 법 - 저, 술, 편, 집

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

개발자가 기술 블로그에 쓰는 글은 크게 저, 술, 편, 집 4가지로 나뉜다.

저(著) : 개발기는 목차를 잘 잡아서 본문부터 쓰자

저(著)는 직접 경험한 것을 쓴 것이다. 개발 과정과 결과를 다룬 개발기를 쓸 때는 무엇보다 목차를 잘 구성해야 한다.

개발 여정을 거치면서 여러 시행 착오를 겪을텐데, 최종적으로 성공한 루트와 실패한 루트를 잘 구분해야 한다. 되돌아가거나 빙 둘러간 루트를 제외하고 최종적으로 성공한 루트만 남겨놓으면, 이것이 아키텍처나 알고리즘, 모델, 플로 등이 되므로 이것을 기준으로 목차를 잡으면 된다. 그 외의 것들은 최종 루트 다음에 문제해결이나 팁으로 정리해 덧붙인다.

보통 글을 쓸 때는 머리말부터 쓰려고 하는데, 본문부터 먼저 써보자. 그 다음으로 맺음말을 쓰고, 마지막으로 머리말을 써보자. 머리말은 맨 마지막에 생각나는 대로 간략하게 쓰는 것이 좋다.

술(述) : 원전을 비교하고 실험해 풀이해서 쓰자

술(述)은 어떤 것을 분석해 의미를 풀이하고 해석한 것이다. 개발에서 술은 새로운 기술을 자세하게 또는 비유해 설명한 것, 비슷한 용어를 비교해 풀이한 것, 에러 해결 방법 등이 여기에 해당한다.

술에 해당하는 기술 블로그를 쓸 때는 본래 내용을 바탕으로 자기 생각이나 분석, 해설을 덧붙이는 방식을 쓰는 게 좋다.

원전은 사물 하나하나를 설명할 뿐이지 두 사물 사이의 공통점이나 다른 점을 뚜렷이 밝히지는 않는다. 그래서 원전의 두 용어나 대상을 비교하면서 풀이하는 것이 바로 술의 역할이다.

원전의 내용을 먼저 쓰고 비교한 내용을 추가하는 것만으로도 기술 블로그를 쉽게 쓸 수 있다. - GET과 POST의 차이

원전의 내용을 직접 실험해 비교한 뒤 그 내용을 정리해 풀이할 수도 있다. 실험한 결과를 잘 정리하기만 해도 좋은 글이 된다. - MySQL Ascending index vs Descending index

개발자의 기술 블로그는 어떤 경우에도 모두 통용되는 완벽한 답이나 공식을 낼 수 없다. 단지 특정 상황에 적합한 방법을 찾아내고 추천할 뿐이다. 따라서 마음을 가볍게 먹고 부담을 덜도록 하자.

편(編) : 순서를 요약하여 쓰자

편(編)은 산만하고 복잡한 자료를 편집해 질서를 부여한 것이다. 그래서 보통 편은 시간 순서로 일어난 일이나 해야 할 일을 쓴 것을 통칭하기도 한다. 프로그램 설치나 설정 순서, 개발 방법, 튜토리얼, 개발자 컨퍼런스 후기 같은 것이 여기에 해당한다.

편을 쓰는 방법은 저술보다 쉽다. 시간 순서로 하나씩 나열해 내용을 쓴 다음, 단계로 묶어서 하위 내용을 간략하게 요약하기만 하면 글이 완성된다.

처음에는 일단 본인이 한 일을 쭉 나열하고 그 내용부터 쓴다. 그다음에 내용을 단계로 묶은 뒤 각 단계에 속한 내용을 요약하도록 한다.

집(輯) : 글쓰기가 두렵다면 자료를 모아 핵심을 엮어서 쓰자

집(輯)은 여러 사람의 견해나 흩어진 자료를 한데 모아 정리하는 것이다. 집은 여러 자료를 책 한권에 모은 것이니 내용을 이것저것 아무렇게나 다 집어넣을 수가 없다. 그래서 자료나 견해에서 요점이 되는 것만 모아야 한다.

집은 내용을 많이 쓰는 것이 아니라 핵심만 간결하게 정리한 것이다. 그래서 글 전체가 길지 않고 내용이 각각 나열되어 있다. 기술 블로그에서는 명령어 모음, 팁, OO가지 규칙 같은 것이 집에 해당한다.

집이라고 해서 반드시 여러 사람의 견해나 자료를 모아야만 하는 것은 아니다. 본인이 경험에서 터득한 것을 핵심만 정리해서 나열해도 좋은 집이 될 수 있다. - 13 Simple Rules for Good Coding (from my 15 years of experience)