발표자는 Jessica Garson. 트위터 개발자 애드보케이트입니다.
예전에는 기술 에반젤리스트 뭐 이런 표현을 많이 쓰는데 요즘에는 애드보케이트를 더 많이 쓰는 것 같습니다. 트위터도 그렇고 AWS도 그렇고~ 에반젤리스트는 기술에 집중한다면 애드보케이트는 좀 더 사용자에 집중하는 느낌입니다.
튜토리얼을 공식적으로 테크니컬 라이터가 작성하기도 하지만, 발표자의 주요 업무(?) 중 하나가 개발자의 문제 해결을 위한 튜토리얼 작성이라고 합니다. 레퍼런스 가이드는 각각의 기능을 설명하지만, 특정 문제에 대한 해결책을 안내하지는 않습니다. 문제 해결을 위해서는 다양한 기능 요소들을 적절하게 조합하고 풀어내는 것이 필요한데 그런 일은 주로 커뮤니티에서 콘텐츠를 많이 만들어내고 있죠. 하지만 개발자 애드보케이트가 그런 역할을 하거나 아니면 커뮤니티에서 잘할 수 있도록 지원하게 됩니다.
Writing a perfect technical tutorial
1. 왜 튜토리얼을 쓰는가?
기술적인 문제를 쉽게 접근하고 해결할 수 있도록 안내하고자 할 때
잘 작성한 튜토리얼은 공유의 기쁨을 누릴 수 있음
실제 경험한 문제 해결 과정을 설명하는 것이 많은 도움을 줄 수 있음
- 뭐 어떤 글이든 마찬가지입니다만 튜토리얼은 그냥 이런 것이 있어라고 소개하는 것보다는 이런 문제를 이렇게 해결할 수 있어라는 걸 소개하는 성격이 강하다는 겁니다.
2. 쓰기 전에 할 일들
어디에 쓸지 고민. 가능하다면 개발자들이 쉽게 접근할 수 있는 플랫폼을 선택하는 것이 좋음
트위터 같은 경우 공식 사이트에서도 작성하지만 별도 플랫폼을 이용하기도 함
(바로 작성하기도 하고 개인 블로그 등에 작성한 내용을 가져오기도 하고)
dev.to/twitterdev 또는 dev.to/aws처럼 dev.to 플랫폼을 많이 활용하고 있음
3. 어떻게 시작하나요?
목적(문제 해결 대상)이 무엇인지 누구를 위한 글인지 명확해야 함
예로 작성한 코드가 이야기 구조를 가지고 있다면 튜토리얼로 좀 더 쉽게 변환할 수 있음
코드 작성 과정을 녹화해서 실제 과정을 검토해보는 것도 도움이 됨
- 개발자가 작업하는 과정을 녹화하거나 관찰하면서 문서를 작성하기도 하는데 스스로 코드를 작성하는 과정을 녹화하는 것도 도움이 될 수 있군요. 그냥 작업을 복기하면서 문서를 작성하면 아무래도 그냥 넘어가는 부분이 생기고 그런 부분이 튜토리얼 문서를 읽는 독자에게 장벽이 되기도 합니다. 녹화를 활용하는 것이 좋은 방법이기는 하지만 시간이 많이 소요된다는 것이 가장 큰 어려움이 아닐까 싶습니다.
4. 예시
이야기 구조가 있는 코드를 단계별 튜토리얼로 작성
각각의 문제를 어떻게 해결했는지 풀어내고
마지막에 결론에서 실제 적용 방법을 요약해서 설명
- 실제 작성을 코드 단위로 진행해야 하는데 하나의 함수 안에 모든 로직을 다 집어넣으면 문제 해결은 되겠지만 이를 설명하기가 쉽지 않습니다. 단계별로 어떻게 해결해나가는지 보여주는 구조가 필요하다는 이야기입니다.
테크니컬 라이터 모집 공고에서 이야기하는 개발 능력은 어떻게 보면 개발자가 작성한 코드를 이야기 구조로 재작성하는 능력도 필요하다는 것이죠.
5. 리뷰는 어떻게
동료와 해당 주제 전문가를 적절하게 섞어서 리뷰를 진행하는 것이 최선
- 물론 실제 독자가 될 이들에게 리뷰를 받는다면 더 좋겠죠. 리뷰 단계에서 수집된 피드백을 어떻게 반영할지도 고민되어야 합니다. 피드백에 따라 글의 방향이 완전히 바뀔 수도 있고
6. 배포하기 전에 할 일들
보통은 트래픽을 성공의 척도로 사용
성공적인 콘텐츠는 독자가 진짜 문제를 해결했다는 피드백을 주는 것
그리고 새로운 버전 릴리스 시에는 콘텐츠를 갱신하거나 새로운 콘텐츠를 만들어주어야 함
- 양적인 측정은 간단하고 사실 맘만 먹으면 쉽게 조작이 가능합니다. 콘텐츠를 늘리거나 SEO를 조금만 신경 쓰면 양은 어느 선까지는 늘어날 수 있거든요. 하지만 요즘 같은 경우 공유를 통한 폭발적인 트래픽 증가는 쉽지 않습니다. 정말 도움이 되는 글이 아니라면 읽거나 공유할 필요가 없으니깐요.
유튜브라면 좋아요의 숫자, 블로그나 문서 형태라면 공유 속도, 숫자 또는 댓글 등으로 평가할 수 있겠네요.
QnA
* 스크린숏
제품 릴리스마다 스크린숏이 변경될 수 있음
소소한 변경은 넘어가더라도 중요한 UI 등의 변경은 업데이트해주어야 함
- 제품 매뉴얼이라면 당연히 릴리스 시점에 맞추어 업데이트하겠지만, 튜토리얼처럼 퍼진 콘텐츠는 업데이트가 쉽지 않습니다. 문제 해결의 방식이 바뀌면 아예 새로운 콘텐츠가 나와야 할 수도 있어서~
그래서 가능하다면 튜토리얼 같은 글은 적용한 버전과 시점을 명시해주는 것이 좋습니다.
공유 과정에서 그대로 글을 퍼가는 이들도 있기 때문에 나중에 통제가 어려운 경우도 있고요.
* 튜토리얼과 가이드
튜토리얼은 좀 더 독자 중심적인 글이라고 생각함
단계별 조리법 같은 느낌이랄까~
실제 독자(개발자)의 입장에서 코드를 작성하는 과정을 설명
참고로 Jessica Garson의 작년 세션에 이어지는 이야기라고 합니다.
작년 세션을 못 보신 분들은 아래 링크를 참고하세요.
Creating Quality Sample Code
