Write the docs 2019 서울 : '블로깅과 테크니컬 라이팅

노트 필기식으로 작성한 내용이기에, 존댓말을 사용하지 않은 점 참고하시기 바랍니다.
또한, 다소 정리되지 않는 부분이 많은 점도 참고하시기 바랍니다.

Write the docs 2019 서울 : 블로깅과 테크니컬 라이팅
2019년 3월 23일 토요일 오후2시
마루 180 이벤트홀

소개

Read the Docs : 문서 호스팅 서비스
Write the Docs (Portland, Oregon)
https://slack.writethedocs.org
김대권님 (서울)
‘#wtdseoul’

글 쓰는 개발자 모임 - 글또 (변성윤 님 - 쏘카) (14시 30분 시작)

글을 꾸준히 작성하기 위해 만든 모임 이야기
https://zzsza.github.io 쏘카 데이터 그룹 머신러닝 엔지니어
2017년 12월 (까먹는게 싫어서) 개발블로그 시작
글또 : 글쓰는 또라이가 세상을 바꾼다 (평균 연차 1~3년차 / 주니어 개발자)
(*강제로 글을 쓰게 만드는 환경을 제공, 글을 쓰면 환급받는 방식으로 습관을 들임)
=> 글 쓰는 습관 형성을 목표로
글 공유 플랫폼 -> 페이스북 그룹으로 공유.

좋은 테마 찾고 Fork 하고 Repo 이름 바꾸고 git clone 해서 로컬 받고 _posts 에 글 작성

시리즈 글, 번역, 해결 방안, 참여후기, 정보 전달글, 프로젝트 글, 회고/일지 글, 책리뷰, …

에러가 왜 발생했는지, 원인부터 파악하여 해결방안까지 작성.

필히 점검하는 것
오타 없는가?
글 전개 방식이 자연스러운가?
처음 보는 사람도 이해가능한가?
블로그 가독성은 어떤가? (심지어 블로그 디자인도 점검.)
이미지 품질은 어떤가?

틀린내용도 쓸 수 있다 (책을 쓰지 않는 이상은, 블로그는 나만 보는 전용으로 만드는 것이기때문에 그냥 고치면 되지~로 접근하면 된다)

페이스북 그룹에서 슬랙으로 변환 후 더욱 더 적극적이고 다양한 커뮤니티가 형성되어 고민도 나누고 해결책도 강구하는 계기가 되었음.

25명 글을 2주마다 피드백하심.

결과
구성원들의 글쓰기 역량 상승, 높은 충성도, 이직할 때 도움, 양질의 글로 개발 생태계에 기여, 사람을 만날 수 있는 연결 고리가 되었음.

자동화에 대한 내용 : 운영 자동화 -> 운영하는 사람의 리소스 효율적으로 사용
(Google Calendar + Slack 연동은 테스트, 추후 봇을 만들어서 오타 및 띄어쓰기 점검하겠다고 하심)

==> 어찌됐든 여전히 글 쓰는 것은 어렵다…..

예치금이 존재하는 강제 글쓰기 모임 (1기수 : 6개월)
상호피드백
꾸준한 동기
같은 분야의 사람들끼리 좋은 시너지
형태는 없고 린하게 방식을 바꾸기

zzsza@naver.com (메일, 페이스북) data.scientist(인스타그램)

기술 블로그 생존 전략: 구글 시대의 글쓰기 (김대권 님- 당근마켓)

당근마켓 소프트웨어 엔지니어 (인프라/클라우드)
44bits.io 팀블로그 운영중이심.
=> 따라서 ‘44bits.io 생존전략’ 이야기

왜 글을 쓰고 ‘공개’ 할까요?
사람들은 블로그의 글을 어떤 경로로 읽게 될까요?

소셜미디어(Twitter 나 Facebook)를 통한 유입

즉각적인 반응 : 기분이 좋아요. (심지어 잘 공유되면 수백, 수천명이 유입됨)
짧은 생명력 : 짧으면 3일, 길어도 1주일. (이 것은 Tweet 의 특징과 유사함.)
팔로워가 없으면, 효과도 없다.
Oraganic Search ( = 구글 검색)
2014년 1월에 작성한, 도커(Docker) 튜토리얼 글 작성시, 당시 아무도 사용하지 않았던 기술이었기에 그 때부터 지금까지 꾸준히 읽혀지고 있음.
지속적인 유입 : 즉, 검색엔진에 노출이 되면 짧으면 몇 주, 길면 몇개월
느린 반응 : 예측이 어렵다. 즉각적인 반응이 없음. (구글은 방문 신뢰성을 기반으로 톱에 산정) .. 그러나 점차 쌓이면 지속적으로 유입이 될 수 있다.
즉, 컨텐츠가 더 잘 발견 되기 위해선, 소셜 공유로 단기적으로 방문자 만들고, 검색 유입을 통해 장기적인 관점을 갖춰져야한다.

본론! 어떻게 하면 글이 검색될까?
(구글은 왜 내 글을 검색 결과에 보여줄까? = 다른 사람들의 문서는 어떻게 선택될까?)
검색엔진은 거대한 추천 시스템이다.
즉, 구글은 수집한 문서들 가운데 ‘검색 키워드’에 대해 가장 ‘추천할만한 글’을 정렬해서 보여준다. 공신력이 높다고해서 꼭 보여주는 것이 아니다 (*구글 ‘Search Quality Rating General Guidelines’ 참고.. 예제도 파악해보자)

좋은 기술 블로그를 만들어 나가기 위한 8가지 제언 (nacyot 작성, 44bits 기술 블로그에서 공개)

문서 관점 : 하나의 웹 문서는 그 자체로 완결되어있다. 구글은 사이트가 아니라 웹문서를 찾아준다.
웹문서 하나하나 질을 높이는 것이 가장 중요하다.
메타데이터(문서에 숨겨진 데이터, 기계만이 알아보는 데이터), 제목, 본문 구조
(*김대권님은 메타데이터가 중요하지 않는다고 생각하신다)
1) 좋은 제목은 본문의 핵심 키워드가 포함되어야한다. (물론, 키워드만 넣어서 억지로 끌어올리는 방법은 먹히지 않는다)
2) 좋은 제목은 본문을 잘 드러내야한다.
3) 좋은 본문이 없다면 좋은 제목도 가치가 없다.

구글은 질 좋은 컨텐츠를 알아볼 수 있다.

글을 잘 완성시켜야한다. (사이트 자체에 신뢰성을 떨어뜨리는 일인다.)
단순히 대충 정리하던 내용을 작성하면 안된다.
지양해야하는 글 = 추천할 가치가 없는 글들 (책도 마찬가지)
완성되지 않는 문장들로 작성된 글
개인 노트를 그대로 공개한 글
직접 작성한 내용이 없는 글
설명보다 코드가 긴 글
링크만 모아놓은 글
적절한 분량의 글을 작성하자.
7분안에 읽히는 글을 작성하자 (1페이지 1분, 1페이지 800자 계산시, 약 5600자 정도)
짧은 뉴스는 2천-3천자 내외
긴 튜토리얼은 2만 - 3만자 내외
이 것보다 짧은 글은 지양하자. 이 것보다 긴 글은 나눠서 쓰는 걸 고려해보자.
글의 형식을 정하자.
What nobody tells you about documentation 참고. (* Read the docs는 확실히 차별화가 있음)
Tutorials, how to guides, references 위주
블로그에는 ‘튜토리얼’, ‘하우투’, ‘해설’, ‘뉴스기사’, ‘에세이(…는 좀 애매하다)’ 위주로 작성하는 것이 좋다.
… 사실은 좋은 미디어들은 이미 지키고 있는 기본 중의 기본! 그리고 좋은 글을 작성한다.

사이트 관점 : 웹문서와 달리, 개별적으로 평가 받는 것은 아니다.
PageRank 가 중요한 이유. (특히, Wikipedia는 1위. 따라서 wikipedia 에서 referred 된 링크는 순위가 높다)

컨텐츠 관리가 가능한 도구를 사용하자.

Static Site Generator를 주로 사용하는다. 그러나 Headless CMS사용하는 것을 추천한다.
보존 그리고 보존
10년 이상 유지되는 기술 블로그를 떠올려보자. 많은 사이트들이 자연도태되어 5년 이내로 사라진다. 즉, 장기적으로 키울 생각을 가지고 운영해보자.

실전편 (처음 블로그를 시작하는 분들을 위하여)
관심사 -> 키워드 -> 글쓰기 -> 공유

먼저 자신이 자신있는 관심사들을 정리해보세요.
글을 쓰고 싶은 키워드를 정하고 구글에서 검색해보세요.
아직 좋은 글이 별로 없는(!), 적당한 범위의 키워드를 정합니다.
(ex : 파이썬 > (적합 키워드) > 파이썬 array 타입의 reverse 함수 사용법)
5천자 이상의 글을 작성. 제목에는 반드시 키워드를 포함. 구조화된 글을 가지고 작성하자.
게시하고 공유하자.
기다리자 (**존버) = 티끌모아 태산

To. 지식 공유를 시작하려는 개발자
From. 당신의 든든한 서포터 Developer Relations 팀 (홍연의 님 LINE+)

이메일 : yeoneui.hong@linecorp.com
LINE+ DevRel 팀에 입사하신지 4개월차.

Developer Relations (DevRel) 팀이란??
국내에 많이 존재하는 것이 아니다.
(회사마다 좀 다를 수 있고, 같은 팀안에서도 다른 일을 하는 분들이 많다.)
기술 블로그 운영 (engineering.linecorp.com), 페이스북 운영 (fb.com/line.developers), 트위터 운영(@line_developers)
개발 컨퍼런스 / 세미나 / 커뮤니티 후원 (메일로 문의)
LINK DEV, LINE Developers Meetup (19년 4월 예정)
즉, 브랜딩 작업, 지식공유 팀

Developer Relations 팀엔 어떻게 오게 되었나???
첫 직장은 IT 도서 기획…
분야는 IT, 주변엔 개발자, 잘(?) 할 수 있는건 콘텐츠 기획, 재밌는 건 마케팅, 보람을 느낀 건 내가 한 일이 누군가에게 도움이 된다는 것.

Public Relations (PR) 팀 vs. Developer Relations (DR)팀 …으로! 보면 된다.

To. 지식 공유를 시작하려는 개발자에게
블로그, 책, 영상, 강의, 발표 … 는 힘들다…
지식공유 = 내 인생의 또 다른 기회를 가져올 수 있다!

Technical Writing 팀이 운영중이고, 담당하시는 개발 인력들이 직접 작성함.
작성에 도움이 될 수 있도록 피드백을 제공. 다른 나라쪽 DR팀에서 직접 번역도 검수.

사용자를 외면하지 않는 릴리스 노트 (조은별 님 - 시큐아이)

이메일 : jogamza@gmail.com
기술 문서를 작성하는 일을 하심.
어떤 고민을 하면서 주로 어떤 식으로 작성하시는지 경험을 공유하심.
IT 출판사 편집자 -> 보안회사 테크니컬 라이터 개발팀 -> 기술 + 글쓰기

테크니컬 라이터의 일
사용자 매뉴얼, 릴리스노트, API 문서
화이트페이퍼, UI 용어/메시지, 개발 계획서, 테스트 계획서
기술블로그 (온라인 콘텐츠), IT 도서 …
주로, 사용자 매뉴얼, 릴리스노트, API 문서, 화이트페이퍼, UI 용어/메시지 까지하심.

릴리스 노트의 정의

문제를 정의하고 해결점을 기술한 문서
1. 신규 기능
2. 개선된 기능
3. 오류 수정
4. 개발자 코멘트
연관 없는 항목이 나열된 목록
간결하고 요약된 문장
구성 포맷

날짜, What’s New, Bug fixes 등으로 구성
대상이 누구인지에 따라 릴리스노트를 작성하는 방식이 좀 다르다.

App Store에 올라온 릴리스 노트들 (대강 사용된 노트와 자세히 써 있는 노트)
Blizzard 게임 Overwatch 게이머들을 위한 릴리스노트
Github Desktop 개발자를 위한 릴리스 노트
시큐아이 릴리스노트 (문서에 대한 구조/카테고리를 일관성있게 작성하는 것을 초점으로 한 릴리스노트)

릴리스 노트의 포맷 예제
[신규 기능]

XX 메뉴에 고급 검색 기능을 추가했습니다.
OO 메뉴에 검색을 저장하고 나중에 다시 실행할 수 있는 기능을 추가했습니다.
[개선된 기능]
보기(Show) 메뉴에서 ‘다음 일주일간의 약속’과 ‘활성상태의 약속’에 접근하는 속도를 개선했습니다.

릴리스 노트 사전 준비 : 문제, 원인, 해결 식으로 진행
더블플레이 슬라이딩 규칙이 신설되었다.

문제 : 더블플레이 상황에서 연계 플레이 하는 유격수나 2루수 부상 위험이 크다.
원인 : 베이스에 닿을 수 있다 판단되면 수비 방해를 선고하고 …
해결 : 네이버후드 플레이는 인정되지 않으며, 수비수는 반드시 베이스를 정확히 밟아야하고 주자도 베이스만을 향해서만 슬라이딩을 해야한다.

야구 팬을 위한 릴리스 노트 작성 : 코멘트 등을 추가하여 더 쉽게 접근이 가능하도록 한다.
[더블 플레이시 슬라이딩 규정 신설]
주자가 더블 플레이를 막는 목적으로 고의적으로 접촉하거나 시도할 경우, 주자와 타자를 모두 아웃 될 수 있습니다.
네이버후드 플레이가 인정되지 않으므로, 수비수는 반드시 베이스를 밟고 있어야합니다.

네이버후드 플레이 : 2루 베이스를 밟지 않아도 아웃으로 선언해주는 암묵적인 행위

야구 전문가를 위한 릴리스 노트 : 다소 간결하게 작성이 가능하다.
[더블 플레이 시도시 슬라이딩 규정 신설]
주자는 올바르게 베이스를 위해 슬라이딩해야합니다.
수비측 내야수는 반드시 베이스를 밟고 있어야합니다.
네이버 후드 플레이가 인정되지 않습니다.

릴리스 노트 작성시 고려할 것
제품/사용자 특성 :누가 읽는 것인가? 일관된 문서 포맷 : 어떻게 읽는 것인가?
세 줄, 다섯줄 요약 : 무엇을 읽는 것인가?
릴리스 노트 포맷에 대한 룰을 정확히 정하자.

개발자는 왜 블로그를 해야하나요? (이동욱 님 - 우아한 형제들)

왜 블로그를 해야하는지, 블로그를 왜 운영을 잘해야하는지에 포커스

우아한 형제들 백엔드 개발, 한국 JetBrains 사용자 모임 운영진, jojoldu.tistory.com 운영
트래픽과 데이터가 많기에 성장할 여지가 있는 회사로 PM

블로그 주말 방문은…..ㅋㅋㅋㅋㅋ

티스토리 스킨으로 아이덴티티 보여줌.
티스토리 댓글 대신 Github 댓글로 교체.
티스토리는 마크다운 파일을 지원안하기 때문에 markdown-tistory 라이브러리 만듦.
=> 블로그 좋아하고 개선하고 혜택을 받은 사람이라고 말함.

블로그를 하면 좋은 이유

광고비 : Google AdSense 에서 매일 $1 ~ $5 (PV 1만에 $5 - 10 정도)
기고 & 집필 요청 : 출판제의, 신간 도서 추천평, 신간 도서 칼럼, 잡지 기고 등등
세미나 초대권 : 이동욱 님은 OKKY 세미나 연사로 초대되기도 하심.
인지도 : 타회사 Wiki에 내 블로그가 링크, referred 됨.
인터뷰와 식사 제공(?) : 마이크로소프트웨어 인터뷰, 인프런 인터뷰
이직 : 멀리서 세미나 발표로, 책으로 보기만 했던 개발자분의 채용 추천, 이력서 코칭도 직접 받음.
1. 추후에 이동욱님 블로그에 기재하심.
사내 기술 블로그 : 작성 요청에 부담이 올 수 있음. (지원자들이 사내기술 블로그 작성할 수 있다?? 이걸로 과연.. 지원할까?)

블로그를 하면 좋은 이유(2) : 왜 블로그를 해야하나요?
연봉 / 회사 / 직위 / 재산을 빼고 ‘나 자신’을 어떻게 표현할 수 있을까…?
나는 무슨 개발자일까? -> 블로그가 그걸 가능케한다! 개발자들에게 블로그는 나 자신을 나타내는 아이덴티티!

결말
젠킨스 마스터 책 “아무리 흐린 잉크라도 좋은 기억력보다 낫다.”

개발 관련 기술 블로그 운영하기 (변정훈 님 - BlockchainOS)

(outsider) 님
2007년 5월 15일 12시 25분 첫 글 집필
전체 연도별 글 (총 1,413개)

글 작성 목표
3일에 글 1개
글 1개에 짧게는 2-4시간
글 1개에 길게는 2-3일
퇴고는 잘 하지 않는다.
문장을 다듬는 거에 너무 시간을 허비지 않는다.

글 주제
개발하면서 적을 수 있는건 전부
새로운 도구, 환경 설치/설정
새로 알게된 라이브러리/도구의 사용법
최근에 겪고 해결한 장애(트러블슈팅)와 처리방법
개발관련 공유할 만한 내용
글을 쓸 주제는 항상 생각하고 있다

나보다 모르는 사람 —— 나(outsider 님) —— 나 보다 잘 하는 사람

Day One 노트앱 사용

왜 개발 블로그를 운영하는가?
공부할 게 많으니까 개발 블로그를 운영한다. = 글쓰는 것이 곧 공부이다.

처음에 글 쓴 이유
배운걸 자꾸 잊어서
전에 설정해 본 적 있는데 기억이 안나서
겪어본 장애였는데 어떻게 해결했더라…

어디에 적을까?
개인 노트
TIL (Today I Learned)
공개 블로그 (outsider 님 선택)

블로그를 작성하는 것이 지식을 습득하는 과정,
단순히 겪어보거나 읽어보는 지식 이상으로 습득하는 과정이 필요하다.

블로그는 회고와 비슷하다

글을 공개로 쓸 때 장점
누구나(1년 또는 10년 뒤의 나) 이해할 수 있어야한다
글로 정리하려면 잘 알고 있어야한다
글로 정리하면서 다시 고민해 볼 수 있다
reputation이 1 올랐습니다

글의 흐름
하고자 했던 일 (Context)
경험한 문제 상황 정리 (격리된 상황)
시도해 본 방법(내가 아는 지식)
왜 동작이 안되는가? 왜 동작하는가?(가설)
문제 상황 재현
예제 코드
관련 링크
개념 설명

Stack Overflow 에서 말하는 MCVE (최소한의, 완성된, 입증가능한 예제)
Minimal : 문제를 재현할 수 있는 가장 적은 코드를 사용하라
Complete : 문제를 재현하는데 필요한 모든 부분을 제공해라
Verifiable : 실제로 해당 문제를 재현하는지 코드를 테스트해라
and Verifiable Example : 이를 위해 입증가능한 예제

알고 있는 내용이더라도 글로 적으려면 공부가 많이 필요하다
공유 문화를 좋아하신다
공유를 통해 남의 경험에서 배우고 시간을 줄인다
일하면서도 글을 많이 작성한다

Slack
Issue Tracker
Wiki

글을 지속적으로 쓰려면 어떻게 해야하나요?
저도 잘… (습관이 된 것 같아요)

사람들이 많이 보는 글
JavaScript에서 String을 Number 타입으로 바꾸기 (2009/08/19 01:09)
Ubuntu 의 apt-get 명령어 정리 (2009/06/23 02:52)
GET과 POST의 차이 (2009/03/31 22:53)
알고 있어야할 8가지 정규식 표현 from nettuts+
제발 a href=“#” 좀 쓰지 말자 (2008/10/22 22:41)

통계
Oragnic Search 위주

기술블로그는 Facebook 을 신경 안 쓸 수 없다
이 분 블로그도 주말에는…..ㅋㅋㅋㅋㅋ

참고사항
강규형 님 (Google Analytics 를 이용한 블로그 콘텐츠 인게이지먼트(Engagement) 추적)

돈이 되나요? 안됩니다!