分かりやすいドキュメントを書く「テクニカルライター」という仕事 / About the job "Technical writer" who writes easy-to-understand documents

Slide 1

Slide 1 text

LINE Technical Writing Meetup vol.1 分かりやすいドキュメントを書く「テクニカルライター」という仕事 LINE Corporation Developer Content Team Yoshiko Horikoshi 11th March 2021 19:00-21:00

Slide 2

Slide 2 text

1: これだけ気を付けて書いてもらえるとみんな幸せになるポイント2つだけ 2: 分かりやすいドキュメントを書く「テクニカルライター」という仕事 3: Questions and Answers 11th March 2021 19:00-21:00 LINE Technical Writing Meetup vol.1

Slide 3

Slide 3 text

⾃⼰紹介

Slide 4

Slide 4 text

はじめまして「ほりこし」です

Slide 5

Slide 5 text

LINE Corporation Developer Content Team

Slide 6

Slide 6 text

2020年1⽉から LINEでテクニカルライター

Slide 7

Slide 7 text

Yoshiko Horikoshi @mochikoAsTech プログラマ（3年）広報（4年）インフラエンジニア（7年） 2020年1⽉からLINEでテクニカルライター

Slide 8

Slide 8 text

きみきみ、⼀緒にテクニカルライターしてみないかね︖

Slide 9

Slide 9 text

1. テクニカルライターという職種があること 2. LINEにはテクニカルライティング専⾨のチームがあること⽮崎さんから話を聞くまで知らなかったこと

Slide 10

Slide 10 text

「知らなかった︕」という⼈の⽅が多いのではないか︖

Slide 11

Slide 11 text

今⽇の内容 Agenda

Slide 12

Slide 12 text

もともとインフラエンジニアだった私が LINEに⼊るまで知らなかった 1. テクニカルライターという職種があること 2. LINEにはテクニカルライティング専⾨のチームがあることの2つについてお話しします

Slide 13

Slide 13 text

技術も好きだし、ドキュメントを書いたり⼈に教えたりするのも好きだ、という⽅に「こういう仕事もあるんだ︕」と発⾒してもらえたらいいな

Slide 14

Slide 14 text

もっと⼿前のそもそもから話すと

Slide 15

Slide 15 text

No content

Slide 16

Slide 16 text

LINE Technical Writing Meetupは、テクニカルライティングをテーマにした技術者向けのミートアップです。エンジニアをしていると、⽇々仕事でドキュメントを書いたり読んだり、あるいは個⼈的に調べたことをブログにまとめたり、公私を問わず技術的な⽂章に触れる機会が多いと思います。もっと分かりやすいドキュメントが書けるようになりたいな、複雑な技術のこともうまく伝えられるようになりたいな、そんな⾵に「書くこと」や「つたえること」について課題感を持っている⽅も少なくないのではないでしょうか。このミートアップでは、LINEでテクニカルライティングを専⾨としているメンバーが集まって、もっと「分かりやすくつたえる」ための知⾒を共有していきます。

Slide 17

Slide 17 text

No content

Slide 18

Slide 18 text

テクニカルライティングを専⾨としているメンバーっていったいだれ︖何してる⼈なの︖

Slide 19

Slide 19 text

1. テクニカルライターって何をしてるの︖何を書くの︖ 2. ドキュメントはどうやって書いてるの︖ 3. どんなメンバーで仕事をしてるの︖ 4. ドキュメントを書く以外にこんなこともしているよ 5. でもドキュメントを書くだけだと技術⼒が下がらない︖ 6. どんな⼈がテクニカルライターに向いてるの︖ こんな流れで話をしていきます

Slide 20

Slide 20 text

Slide 21

Slide 21 text

LINEのテクニカルライターは、主に社外の開発者向けにドキュメントを提供するという仕事をしています

Slide 22

Slide 22 text

⾃社で運営するサイトに「LINEログイン」ボタンをつけて、エンドユーザが LINEのアカウントでもログインできるようにしてあげたい︕

Slide 23

Slide 23 text

「LINEログイン」ボタンをつけたい︕ でもこれ、どうやって実装すればいいのかな︖

Slide 24

Slide 24 text

LINEのテクニカルライターは、そういう⼈のためにドキュメントやAPIリファレンスを書いて公開しています https://developers.line.biz/ https://clova-developers.line.biz/

Slide 25

Slide 25 text

ドキュメントは⽇本語と英語で同時公開

Slide 26

Slide 26 text

Slide 27

Slide 27 text

Slide 28

Slide 28 text

マークダウンでドキュメントを書いてローカルの開発環境でデプロイして確認します

Slide 29

Slide 29 text

GitHubのリポジトリへプッシュしてプルリクエストを作ります

Slide 30

Slide 30 text

別のライターやプロダクトの担当者が Sandboxで確認してレビューします

Slide 31

Slide 31 text

レビューを終えてmasterへマージすると Jenkinsがデプロイしてくれてリリース完了

Slide 32

Slide 32 text

あとはリリースされたらみんなで「わーい」と喜びます︕

Slide 33

Slide 33 text

先に⽇本語で書いてから英訳することもあるし英語で書いてから⽇本語訳することもある

Slide 34

Slide 34 text

仕様インプットのために最初に30分くらい開発担当とのミーティングをすることもあるし仕様が書かれたWikiをもらって書く場合もある

Slide 35

Slide 35 text

2020年下期は半年で116回リリースしていたのでおおよそ1⽇に1回はリリースしている

Slide 36

Slide 36 text

新しいサービスのドキュメントを書きつつ今あるドキュメントも直したり拡充したり

Slide 37

Slide 37 text

Slide 38

Slide 38 text

Slide 39

Slide 39 text

Developer Content Team 2021年3⽉時点

Slide 40

Slide 40 text

余談︓ 社内に通訳翻訳チームがいて必要なミーティングには通訳が⼊ってくれます

Slide 41

Slide 41 text

Slide 42

Slide 42 text

Slide 43

Slide 43 text

ドキュメントを書く以外にこんなこともしています • 他部署が作った社内資料のレビュー • 社内Wikiの構成⾒直し • 社内研修 • 分かりやすい⽂章の書き⽅講座（900⼈） • 教え上⼿になろう講座（900⼈） • 分かりやすい伝え⽅講座（600⼈）

Slide 44

Slide 44 text

Slide 45

Slide 45 text

⾃分で⼿を動かして実装せずドキュメントを書くだけになってしまうと⾃分が「技術」から離れてしまうのでは︖ という⼼配があった

Slide 46

Slide 46 text

実際、テクニカルライターとして働いてみてどうだったか︖

Slide 47

Slide 47 text

杞憂だった︕

Slide 48

Slide 48 text

LINEログインのドキュメント書いて︕ →OAuthを理解する必要があった Messaging APIのFlex Messageのドキュメント書いて︕ →Flexboxを理解する必要があった

Slide 49

Slide 49 text

結局のところ、その機能や実装⽅法、裏側の技術を理解しないと「分かりやすいドキュメント」は書けない

Slide 50

Slide 50 text

よく分かっていないままで体裁だけ整った⽂章をなんとなく書くと「読んだけどよく分からなかった…」となる残念なドキュメントが⽣まれるだけ

Slide 51

Slide 51 text

LINEにはたくさんのプロダクトがあるのでよいテクニカルライターになろうとすれば⾃ずと⾊んな分野の技術を積極的に学ぶことになり技術⼒は衰えない（と思いたい）

Slide 52

Slide 52 text

Slide 53

Slide 53 text

1. 仕様を理解するための技術の素養 2. 分かりやすい⽂章を書くスキル両⽅あれば最⾼だけどどちらかと⾔えば1のほうが重要

Slide 54

Slide 54 text

もともとエンジニアをしていて⽂章を書いたり、教えたりするのも好きだ︕ という⼈はきっとテクニカルライターに向いている

Slide 55

Slide 55 text

Slide 56

Slide 56 text

もともとインフラエンジニアだった私が LINEに⼊るまで知らなかった 1. テクニカルライターという職種があること 2. LINEにはテクニカルライティング専⾨のチームがあることについてお話ししてきました

Slide 57

Slide 57 text

https://linecorp.com/ja/career/position/806

Slide 58

Slide 58 text

No content

Slide 59

Slide 59 text

Slide 60

Slide 60 text

このイベントのアーカイブ動画は YouTubeでご覧いただけます https://www.youtube.com/watch?v=nmFVXJGiCxM

Slide 61

Slide 61 text

61 https://line.connpass.com/event/207045/