개발자의 글쓰기

변수 네이밍부터 릴리스 노트, 장애보고서, 기술 블로그까지, 프로그래머의 글쓰기 고민 끝!

개발자의 글쓰기 능력을 종합적으로 향상하기 위한 이 책을 읽고
블로그 작성에 관련된 부분만 따로 정리해봤다.

요즘은 개발자가 다른 개발자나 사용자, 잠재 고객과 소통하는 일이 잦아졌다.
깃허브(GitHub)등을 통해 개발자가 만든 코드를 공개하고, 개발자 사이트를 통해 외부 개발자와 협력하는 일도 늘었다.
그러다 보니 개발하는 것만큼 글 쓸 일이 많아졌다.

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

1. 주제 의식을 버리고 소재 의식으로 쓰자
   • 소재 우선 글쓰기는 주제 의식이 아니라 소재 의식을 갖고 쓰는 것이다.
     주제 의식이 민족이나 권선징악, 자존감이나 자본주의 같은 추상적 가치를 기반으로 한다면
     소재 의식은 특정한 대상이나 상황에 대한 자기만의 관점이나 생이나 해결 방안을 뜻한다.
     주제 의식은 많은 사람에게 보편적인 주제를 선택해서 더 많은 사람에게 주제 의식을 퍼뜨리는 것이지만, 소재 의식은 독자와 상관없이 대상이나 상황에 맞닥뜨렸을 때부터 그 대상이나 상황에서 벗어날 때까지 겪은 일을 담담하게 정리해서 얘기할 뿐이다.
2. 독자 수준이 아니라 자기 수준으로 쓰자
   • 개발자가 기술 블로그를 쓸 때는 독자를 생각해서 어려운 용어를 일부러 해석해 풀어쓰거나
     쉬운 용어로 바꿀 필요가 없다. 원래 사용하는 용어로 그냥 표기하되
     필요하다면 용어를 정의한 위키피디아 페이지나 세부 내용을 볼 수 있는 사이트나 문건을 링크로
     걸어두면 된다. 기술 블로그란 것은 결국 실력이 비슷한 독자를 위한 것이다.
     독자에게 다 설명하는 것이 아니라 핵심 내용만 쓰고 나머지는 독자가 공부할 수 있게 길만 터놓는 것이
     현명한 방법이다. 그래야 개발자도 자기가 쓰려는 글의 본질에 집중할 수 있다.
3. 재미있게 글을 쓰자
   • 글쓰기 기교는 글을 아름답게 만들고 쉽게 읽히게 한다. 기교를 부리다 보면
     글쓰기가 재미있고 글도 재미있어진다. 글에 재미가 있으면 독자가 활발히 반응하고
     독자의 반응이 활발하면 블로거는 글을 계속 쓸 동력을 얻는다. 글쓰기 기교는 이렇게 선순환을 만든다.

글의 종류별로 목차 잡는 법

1. 기술 블로그의 4종류, 저, 술, 편, 집
   • 저 : 개발기는 목차를 잘 잡아서 본문부터 쓰자
     • 저는 직접 경험한 것을 쓴 것이다. 개발 과정과 결과를 다룬 개발기를 쓸 때는
       무엇보다 목차를 잘 구성해야 한다. 목차만 제대로 잡으면 다른 종류의 글보다 쓰기 쉽다.
       개발기 목차는 1차원 단방향이다. 1장 다음에는 2장이 이어지고, 2장 다음에는 3장이 순서대로 이어진다. 하지만 개발자의 경험은 2차원 양방향이다.
       2차원 양방향 경험을 1차원 단방향 목차로 바꾸는 핵심 방법은 최종적으로 성공한 루트와
       중간에 실패한 루트를 구별하는 것이다.
       개발자가 가장 잘 쓸 수 있는 내용은 본문이다. 목차를 정했으면 머리말부터 쓰지 말고 본문부터 쓰자.
       게다가 개발이 완료되면 아키텍쳐나 알고리즘, 모델이나 플로 같은 것이 산출물로 나오기 때문에
       그런 이미지를 먼저 붙여넣고 글을 쓰면 단번에 몇 단락을 쓸 수 있다.
       그렇게 해서 본문을 쓰고 나면 맺음말을 쓰자. 머리말은 맨 마지막에 블로그에 올릴 때 생각나는 대로 간략히 적는 것이 좋다.
   • 술 : 원전을 비교하고 실험해 풀이해서 쓰자
     • 술은 어떤 것을 분석해 의미를 풀이하고 해석한 것이다.
       개발에서 술은 새로운 기술을 자세하게 또는 비유해 설명한 것, 비슷한 용어를 비교해 풀이한 것, 에러 해결 방법 등이 여기해 해당한다.
       술에 해당하는 기술 블로그를 쓸 때는 본래 내용을 바탕으로 자기 생각이나 분석, 해설을 덧붙이는 방식을 쓰는 게 좋다.
       사람은 어떤 사물을 그 자체로 인식하기보다는 다른 사물과 비교하면서 인식할 때 더 잘 이해한다.
       하지만 원전은 사물 하나하나를 설명할 뿐이지 두 사물사이의 공통점이나 다른 점을 뚜렷이 밝히지는 않는다. 그래서 원전의 두 용어나 대상을 비교하면서 풀이하는 것이 바로 술의 역할이다.
   • 편 : 순서를 요약하여 쓰자
     • 편은 산만하고 복잡한 자료를 편집해 질서를 부여한 것이다.
       보통 편은 시간 순서대로 일어난 일이나 해야 할 일을 쓴 것을 통칭하기도 한다.
       프로그램 설치나 설정 순서, 개발 방법, 튜토리얼, 개발자 컨퍼런스 후기 같은 것이 여기에 해당한다.
       편을 쓰는 방법은 저술보다 쉽다. 시간 순서로 하나씩 나열해 내용을 쓴 다음,
       단계로 묶어서 요약하기만 하면 글이 완성되기 때문이다.
       글을 쓸 때는 한 일을 먼저 시간 순서로 적은 다음, 내용을 다 적는다.
       그런데 이렇게만 쓰면 한 일을 장황하게 나열한 것뿐이므로 글의 완성도가 떨어진다.
       그래서 단계를 만들어서 묶은 뒤 하위 내용을 간략히 요약한다.
   • 집 : 글쓰기가 두렵다면 자료를 모아 핵심을 엮어서 쓰자
     • 집은 여러 사람의 견해나 흩어진 자료를 한데 모아 정리하는 것이다.
       집은 내용을 많이 쓰는 것이 아니라 핵심만 간결하게 정리한 것이다.
       집이라고 해서 반드시 여러 사람의 견해나 자룔르 모아야만 하는 것은 아니다.
       본인이 경험에서 터득한 것을 핵심만 정리해서 나열해도 좋은 집이 될 수 있다.