개발자의 글쓰기 7장 - 기술 블로그 쉽게 쓰고 운영하기

 

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

 

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

'주제 우선, 독자 중심, 주장하는 글쓰기'가 학교를 벗어난 개발자의 글쓰기 방식을 지배해왔다.

그래서 주제가 불분명하고, 독자 수준은 천차만별이며 딱히 주장할 것이 없는 기술 블로그를 써야 할 때는

생각이 정리되지 않고 목차를 잡기 어려워진다.

 

기술 블로그를 읽는 독자의 수준도 일정치않으며 개발자의 블로그는 딱히 주장도 없다.

단지 개발자가 했던 선택과 몇몇 상황에서 더 좋은 방법을 제시할 수 있을 뿐이다.

그래서 개발자에게 적합한 방법 세 가지를 제시한다.

 

소재 우선 글쓰기, 자기 수준 글쓰기, 재미있는 글쓰기다.

 

 

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

주제 의식이 민족이나 권선징악, 자존감 자본주의 같은 추상적 가치를 기반으로 한다면

소재 의식은 특정한 대상이나 상황에 대한 자기만의 관점이나 생각, 해결 방안을 뜻한다.

Ex) 우아한형제들 기술 블로그 “데이터베이스의 자동증가 값을 기본키로 사용할 수 없을 때는?”

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

 

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

모든 독자를 위해 글을 쓴다는 것은 어려운 일이다.

게다가 그렇게 무조건 쉽게만 쓴 글을 읽는 독자가 그 내용을 얼마나 활용할 수 있을지 알 수 없다.

그러니 독자 수준이 아닌 작성자 수준으로 쓰는 편이 낫다.

 

예를 들어 어려운 용어를 써야 한다고 하자. 하지만 어려운 용어를 무조건 풀어서 쓰거나 쉬운 용어로 바꿔 쓸 수가 없다.

개발자가 사용하는 용어는 이미 표준이거나 관습인 경우가 대부분이다.

또한 이해하지 못하는 독자를 위해 일일이 용어를 풀어쓰고 해설하다 보면 본래 말하고자 했던 내용은 한 줄도 쓸 수가 없다.

[잘못된 예]

CSS(Cascading Style Sheets)는 마크업 언어가 실제로 표시되는 방법을 기술하는 언어로, 
...

그러면 이제 반응형 웹에 사용되는 CSS를 알아보겠습니다.
...

이 경우, CSS를 모르는 독자가 1명이라도 있다면 위키피디아 링크를 걸어놓는 편이 낫다.

독자가 이해하지 못할 것으로 예상하거나 추가 정보가 필요한 용어에는 링크를 걸어준다.

 

다만 네이버 D2의 텐서플로우 관련 글에는 GPU 같은 단어에는 링크도 걸지 않고 우리말로 바꾸지도 풀어쓰지도 않았다.

기술 블로그란 것은 결국 실력이 비슷한 독자를 위한 것이다.

모든 걸 설명하는 것이 아닌 핵심 내용만 쓰고 나머지는 독자가 공부할 수 있게 길만 터놓는 것이 현명한 방법이다.

 

셋째, 재미있게 글을 쓰자

글쓰기 기교는 글을 아름답고 쉽게 읽히게 만든다.

재미가 있는 글에는 독자가 활발히 반응하고 독자의 반응이 활발하면 블로거는 글을 계속 쓸 동력을 얻는다.

 

 

02 글의 종류별로 목차를 잡는 법 1 - 저술

 

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

개발한 과정, 튜토리얼, 에러나 버그 해결하는 방법 등 이런 글은 크게 저, 술, 편, 집으로 나뉜다.

글의 목차를 잡아 구조화하여 독자가 읽기 쉽도록 배려하는 것도 있지만, 글쓰기를 부담 없이 시작하고 글을 쉽고 빠른 시간에 완료할 수 있기 때문이다.

 

 

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

저는 직접 경험한 것을 쓴 것이다.

• TensorFlow를 활용한 네이버쇼핑의 상품 카테고리 자동 분류
• Dagger 적용기
• 분산 웹 캐시의 개선 과정

개발 과정과 결과를 다룬 개발기는 무엇보다 목차를 잘 구성해야 한다.

목차는 1차원 단방향이다. 1장 다음 2장.. 순서대로 이어진다.

하지만 개발자의 경험은 2차원 양방향이다. A문제를 해결하려고 B코드를 썼다가 C버그가 생겨서 D기술을 도입하고..

그래서 개발자 머릿속에는 자신의 경험이 길을 잃고 해매다 겨우 목적지에 도착한 모습으로 남아있다.

 

이러한 2차원 양방향 경험을 1차원 단방향 목차로 바꾸는 핵심 방법은

‘최종적으로 성공한 루트와 중간에 실패한 루트를 구별하는 것’이다.

네이버 기술 블로그를 살펴보면

4장에선 카테고리 자동 매칭 모델을 6가지 단계로 나눠 설명한다. 이 모델이 성공한 최종 루트다.

그 과정에서 실패하거나 고생했던 루트는 5장에 4가지로 모아 정리했다.

더불어 최종 루트가 100% 완벽한 루트는 아니므로 6장에서 남은 작업이라는 이름으로 아직 풀지 못한 문제를 덧붙였다.

 

네이버 기술 블로그가 가장 체계적으로 잘 쓰였다고 생각한다. 국내에서 가장 실력있는 테크니컬 라이터가 다듬어서 공개하기 때문이다.

개발기를 쓰려는 사람이라면 모범이 되는 글의 목차를 먼저 보는 것이 좋다.

여기서 하나의 팁을 주자면, 목차를 정했으면 머리말부터 쓰지 말고 본문부터 쓰자.

본문을 쓰고 나면 맺음말을 쓰고 머리말은 맨 마지막에 블로그에 올릴 때 생각나는 대로 간략히 적는 것이 좋다.

 

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

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

• GET, POST의 차이
• Webpack 4의 Tree Shaking에 대한 이해
• MySQL 1175 에러 해결 방안

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

사람은 어떤 사물을 그 자체로 인식하기보다 다른 사물과 비교하면서 인식할 때 더 잘 이해한다.

하지만 원전은 사물 하나하나를 설명할 뿐이지 두 사물 사이의 공통점이나 다른 점을 뚜렷이 밝히지는 않는다.

그래서 원전의 두 용어나 대상을 비교하면서 풀이하는 것이 바로 술의 역할이다.

 

GET과 POST의 차이

[HTTP]
HTTP는 웹상에서 클라이언트와 서버 간에 요청/응답으로 데이터를 주고받을 수 있는 프로토콜입니다. 
...

[GET]
GET은 요청을 전송할 때 필요한 데이터를...

[POST]
POST는 리소스를 생성/변경하기 위해 설계되었기 때문에..

[GET과 POST의 차이]
GET은 idempotent, POST는 Non-idempotnent하게 설계되었습니다..

여기서 GET은 ..

반대로 POST는 ...

[참고]
..

목차를 보면, GET과 POST의 상위 범주인 HTTP 프로토콜과 메소드를 설명한다.

그다음에 GET, POST를 각각 설명하는데 이 내용은 원전인 HTTP프로토콜을 참조한다.

그다음 4장에선 GET, POST 차이에서 두 메소드의 차이를 풀이하고, 마지막 5장에선 참고할 원전과 용어를 링크한다.

위 예시는 개발자가 자기 생각을 이론적으로 펼친 것이다.

그런데 원전의 내용을 직접 실험해 비교한 뒤 그 내용을 정리해 풀이할 수도 있다.

실제로 기업에서는 서비스 성능을 높이기 위해 여러 가지 실험을 많이 하므로 그 결과를 잘 정리하기만 해도 좋은 글이 된다.

 

 

 

03 글의 종류별로 목차 잡는 법 2 - 편집

 

편: 순서를 요약하여 쓰자

시간 순서로 일어난 일이나 해야 할 일을 쓴 것을 통칭한다.

프로그램 설치나 설정 순서, 개발 방법, 튜토리얼, 개발자 컨퍼런스 후기 같은 것이 여기에 해당한다.

• 사용하면서 알게 된 Reactor, 예제 코드로 살펴보기
• 간단하게 구축해보는 JavaScript 개발 환경

시간 순서로 하나씩 나열해 내용을 쓴 다음, 단계로 묶어서 요약하기만 하면 글이 완성되기 때문이다.

서울에서 벗어난 적 없는 사람에게 기차를 타고 부산 해운대에 가는 길을 설명한다면?

 

여기서 편을 통해 단계를 더함으로써 좀 더 질서 있게 보여주자

 

글을 쓸 때는 단계를 만들어서 묶은 뒤 하위 내용을 간략히 요약한다.

1. Git과 Github를 활용한 협업 공간으로 개발 시작하기
	가. Git 저장소 만들기
	나. GitHub에 이슈 등록하기

2. Node.js와 Yarn으로 개발 환경 설정하기
	가. Node.js와 npm, Yarn
	나. Node.js와 yarn 설치
	다. 프로젝트 생성

...

글쓰기에 능숙하지 않다면 처음에는 일단 구조를 생각하지 말고 본인이 한 일을 쭉 나열하자

그렇게 내용부터 쓴 후, 내용을 단계로 묶은 뒤 각 단계에 속한 내용을 요약하자. 이렇게 써야 글쓰기 진도가 나간다.

 

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

집은 여러 사람의 견해나 흩어진 자료를 한데 모아 정리하는 것이다.

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

• 자바스크립트 정규표현식 코딩팁
• 스크롤과 관련된 CSS 속성 3가지
• 좋은 코딩을 위한 13가지 간단한 규칙

반드시 여러 사람의 견해, 자료를 모아야만 하는 것은 아니며 본인이 경험해서 터득한 것을 핵심만 정리해서 나열해도 좋다.

 

기술 블로그를 처음 쓰는 개발자라면 가장 쉽게 도전할 수 있는 글이 바로 집이고 그 다음 편이다.

즉, 편집 글이다. 이런 글은 조회수도 높다.

• OO을 위한 O가지 팁
• OO 언어의 자주 쓰이는 명령어 O가지
• OO을 개발하기 전에 알아야 할 베스트 5

 

 

04 기업의 기술 블로그 운영 팁

 

기술 블로그는 회사의 가치를 높인다

기술 블로그를 운영하려는 기업은 스타트업 중심으로 점점 늘어나는데, 여기에는 3가지 이유가 있다.

1. 채용 직무에 적합하면서 개발 능력이 우수한 개발자 채용에 도움을 준다.
2. 개발 과정에서 생긴 노하우를 체계적으로 축적할 수 있다.
3. 개발자가 스스로 공부하게 만든다.

개발자의 글쓰기는 회사의 문화를 반영한다

단적으로 비교할 수 있는 것이 네이버와 우아한형제들의 기술 블로그다.

네이버는 정형화한 구성과 논문 제목 같은 목차, 세련된 문체와 간결한 표현을 보여준다.

그래서 약간은 건조하고 딱딱한 느낌이 든다.

반면 우아한형제들은 주말 밤에 야근하는 개발자들끼리 대화하듯이 자연스러운 표현과 실감 나는 구성, 자극적인 제목과 제약 없는 묘사가 두드러진다. 그래서 약간은 비전문적이면서 글을 대충 쓴다는 느낌도 든다.

따라서 개발자의 글쓰기 원칙이나 수준을 정하기 전에 회사의 글쓰기 문화를 먼저 정의해야 한다.

 

협업해서 글쓰기, 짝 글쓰기를 해보자

개발에서 짝 프로그래밍이 있듯이 글쓰기에도 짝 글쓰기가 있다. 두 명이 글 하나를 같이 쓰는 방식이다. 짝 글쓰기의 이점은 다음과 같다.

1. 글의 완성도가 높아진다. 서로가 독자 역할을 하며 질문과 답이 오간다.
2. 지식을 보편화할 수 있다. 혼자 글을 쓰면 자기만의 지식 체계가 만들어지지만, 둘이 같이 쓰면 공통된 지식 체계를 만들 수 있다.
3. 팀 회고를 할 수 있다. 개발 과정 및 결과를 글로 쓰면서 자연스레 회고를 하게 된다.
4. 심리적 안정감을 느낀다. 혼자 쓸 땐 글의 수준 및 내용이 적절한지 혼자 판단해야 하지만 둘이 같이 쓴다면 부담이 한결 가벼워진다.

 

이밖에도 팀워크, 소통 향상 등 좋은 점이 있다.

짝 글쓰기의 방법은 짝 프로그래밍에서 쓰는 방법을 사용하면 된다.

 

• Driver & Navigator: 한 명은 글을 쓰고 다른 한 명은 글을 검토하는 방식
• Coder & Adviser: 한 명은 글을 쓰고 다른 한 명은 조언하는 방식. 조언자는 글쓰기 수준이 비교적 높은 사람이 하는 것이 좋다.
• Verbalizer & Listener: 글을 쓰고 난 뒤 한 명은 글을 읽고 다른 한 명은 귀로 듣는 방식. 글을 큰 소리로 읽어보면 부자연스러운 문장에서 말이 막힌다.
• Ping-Pong: 두 명이 번갈아 가면서 글을 쓰는 방식. 목차 단위로 나눠서 쓸 수도 있고, 한 명은 예제 코드를 쓰고 다른 한 명은 예제 코드를 설명하는 식으로 쓸 수도 있다.

 

 

Ref.

개발자의 글쓰기 - 김철수