「LINE Technical Writing Meetup vol.1」を開催しました!

こんにちは、Developer Contentチームのmochikoです。LINE株式会社でテクニカルライターとして働いています。

2021年3月11日(木) に、「LINE Technical Writing Meetup vol.1」をオンラインにて開催しました。テクニカルライティングをテーマにした技術者向けのミートアップは初開催だったため、どの程度みなさんに興味を持ってもらえるかという心配もあったのですが、蓋を開けてみたら600人超の参加申し込みをいただき、当日もQ&Aの時間内では回答しきれないほどの質問をいただいて、大盛況のイベントとなりました。

この開催レポートでは、当日の様子を動画や資料でご紹介していきます。



LINE Technical Writing Meetupってなに?

LINE Technical Writing Meetupは、テクニカルライティングをテーマにした技術者向けのミートアップです。

もともとLINE社内では、テクニカルライターが講師を務める「分かりやすい文章の書き方講座」、「教え上手になろう講座」、「分かりやすい伝え方講座」などを定期的に開催していました。これらの講座の需要や反響がとても大きかったため、折角なので「分かりやすくつたえる」ための知見を社外でも共有してみようよ!ということでこのミートアップをはじめました。

今回は2つのセッションと、みなさんからの質問に回答するQ&Aという構成でお送りしました。



セッション1:これだけ気を付けて書いてもらえるとみんな幸せになるポイント2つだけ

最初のセッションは、テクニカルライター歴20年以上のベテラン、矢崎 誠さん(@yazakimakoto)による「これだけ気を付けて書いてもらえるとみんな幸せになるポイント2つだけ」です。「文章を書くときのポイント」はたくさんあれど、その中でも矢崎さんが特に重要だと考えている「名前を大事にしてほしい話」と「あらかじめ読者との距離を近づけてほしい話」の2つを話してくれました。

セッションの概要

そもそも「分かりやすい文章」とは?

2つのポイントに入る前に、先ずは「分かりやすい文章」ってそもそもどういうものだろう?という話からはじまります。読み手に早く正しく理解してもらえるような文章を書くことで、読み手が使う時間を最小限にしてあげたいですよね、そのために書き手が少し多めに時間をかけて分かりやすい文章を書いてあげましょう、という目的の共有が行われました。

今回の「名前を大事にしてほしい話」と「あらかじめ読者との距離を近づけてほしい話」以外にも、次回以降のミートアップでは、こんな「文章を書くときのポイント」を話していきたいと思います、という将来の展望も紹介してくれました。



ポイント1:名前を大事にしてほしい話

1つめの「名前を大事にしてほしい話」では、文章の中で名前(名詞)を明確にすることの大切さが語られました。「LINEで送るボタン」の説明を例に、次のように文章を分かりやすくしていく各ステップが紹介されました。

  • 変更前の文章(Before)
  • 名前を省略せずにすべて書いた文章(After: Level1)
  • 箇条書きなどを使って少し分かりやすくした文章(After: Level2)
  • 優先度の低い情報を削って簡潔にした文章(After: Level3)


ポイント2:あらかじめ読者との距離を近づけてほしい話

2つめの「あらかじめ読者との距離を近づけてほしい話」では、黒丸の「書き手がこの文章で伝えたいこと」と、オレンジ丸の「読み手がこの文章に期待していること(きっとこんな話が書いてあるんだろう、と思っていること)」を事前に近づけてあげることで、文章が分かりやすくなる、という例が紹介されました。

たとえばお昼どきに「ちょっとお時間いいですか?」とだけ言われると、言われた側はどんな話が来るか分からず、話の方向性が分かるまでは次のように考えてしまって、話が頭に入りづらくなります。

  • お昼ご飯に一緒に行こうってお誘いかな?
  • それとも休憩前に仕事の話をしたいのかな?
  • 他の人とランチに行こうと思ってるんだけど、いいお店知りませんかって質問かな?
  • まさか辞めるっていう相談かな?!

対面での会話なら、途中で「え、ごめん。そもそも何の話?」と聞くこともできますが、文章の場合はそうした臨機応変な軌道修正ができないので、「タイトル」や「概要(リード文)」を使って、最初に「書き手がこの文章で伝えたいこと」と、「読み手がこの文章に期待していること」を近づけて、分かりやすくしてあげましょう、という話でした。

ちなみに矢崎さんの「テクニカルライティング講座」は、LINE Engineering Blogでも連載されています。次回以降のミートアップが待ちきれない方は、ぜひそちらもご覧ください。

動画(0:16:57〜)

資料



セッション2:分かりやすいドキュメントを書く「テクニカルライター」という仕事

2つめのセッションは、堀越 良子(@mochikoAsTech)の、「分かりやすいドキュメントを書く『テクニカルライター』という仕事」です。もともとインフラエンジニアをしていた堀越が、LINEに入るまで知らなかった「テクニカルライターという職種があること」と「LINEにはテクニカルライティング専門のチームがあること」の2つについて話をしました。

セッションの概要

LINEのテクニカルライターってどんな仕事をしているの?

「テクニカルライティング」のミートアップですが、そもそもテクニカルライターってどんな仕事をしているのか、参加者のみなさんはいまいち想像がつかないかもしれません。そこでまずは「LINEのテクニカルライターってどんなことをやっているの?」を紹介しました。

ドキュメントを書く流れについても、できるだけ具体的に説明しました。リリースまでのフローについて「文章を書くだけじゃなくて、リリース作業まで自分たちでやるんだ!」というコメントや、「半年で116回、つまり1日1回リリースしている」というリリースのペースについて「すごい回数!!」というコメントをいただきました。テクニカルライターの詳細な生態を驚きと共に楽しんでもらえたかなと思います。



どんな人がテクニカルライターに向いているの?

分かりやすいドキュメントを書くためには、開発者から渡された仕様を理解できる技術の素養と、分かりやすい文章を書くスキルの両方が必要です。ただ両方あれば最高ですが、どちらか片方しか選べないとしたら、「ある程度の技術知識はあるけれど、文章を書く経験は浅い」という人の方が、LINEのテクニカルライターには向いていると私は思っています。「分かりやすく伝えるにはどうしたらいいかな?」とうんうん考える情熱があれば、ライティングのスキルは後からでもついてくるので、もともとエンジニアをしていて、文章を書いたり、人に教えたりするのも好きだなーという人だったら、きっとテクニカルライターに向いていると思います。

動画(0:47:51〜)

資料



セッション後のQ&Aも盛り上がりました

質問はslidoで受け付けていたのですが、予定していたQ&A(1:17:39〜)の時間を大幅に延長しても、回答しきれないほどの質問をいただきました。みなさんにテクニカルライティングや、テクニカルライターという仕事に興味を持ってもらえて、我々もとっても楽しかったです!全部回答できなくてごめんなさい!

ここでは、いただいた質問とその回答を一部抜粋して紹介していきたいと思います。

Q. ドキュメントを作成するとき、無限に時間を使わないようにするには?

矢崎:お腹が空いたら切り上げる、じゃないですか。あとは、ある程度文章が書き上がって、80%書けたかなと思ったら「もう100%書けました」という顔をして、開発の人にレビューをお願いします。残りの20%を持ち上げて100%にしようとすると、それこそ時間が溶けてしまうので。

堀越:そうですね。私は「Aって書いたほうがいいのかな」「それともBって書いたほうが分かりやすいのかな」と迷いがあると、推敲がいつまでも終わらない気がしています。なので、「AかなBかな」と迷うより、AとBの両パターンを書いて「どっちの方が分かりやすい?」とか、プロダクトの担当者に「どっちの方が仕様として正しい説明ですか?」と聞きますね。テクニカルライターがドキュメントを書く時は、それを読むことで他の人の時間の節約をしてもらいたいと思っています。読む人が30分節約できたとしても、私達がドキュメントを書くことに1時間使ってしまうと、トータルの時間はマイナスになってしまうので、読む人が節約できるであろう時間以上に、書く時間を使わないようにしよう、と思いながら書いています。

矢崎:書く時間を気にしているのが偉いですね。私はさっさとかいて、さっさと出します。迷わない、20年もやっていると迷いが減ります。

Q. 短く簡潔で分かりやすいタイトルをつけるコツは?

矢崎:コツはありません!分かりやすい機能には、分かりやすいタイトルがつけやすいです。一方、分かりにくい機能に、「短く簡潔で分かりやすいタイトル」をつけるのは無理ですね。セッション1で私が紹介した「タイトル」と「概要」の、「概要」の役割が必要なはずなのに、「タイトル」だけで簡潔に説明しようとしているということになりそうです。あきらめて「タイトル」と「概要」をちゃんと作りましょう。

堀越:分かる。あとはどうしても分かりやすいタイトルがうまくつけられない、という時は、そもそも自分も理解できていない時だったりしますね。

Q. 自分の書いた文章が分かりやすかったかどうか判断するには?

矢崎:次の日に読むと分かります。一晩明けても、同じように分かる文章は、だいたい分かりやすいですね。

堀越:既に一度理解してしまったものは、文章を読み直してももう「分かってしまっている」ので、分からなかったときの気持ちにはなるのなかなか難しいんですよね。周りの人に「これさっと10秒で読んでみて分かる?」みたいに、助けを借りるのもいいと思います。ただ「英語が読めるようになる方法が英語で書いてある」みたいな感じで、分かればもう読めるんですよね。分からないと読めないんですよ。

矢崎:なのでお勧めはやっぱり次の日ですね。寝かせて読むのがお勧めです。

Q. Slackで質問するときに回りくどい文章になってしまう。短めの文章を書く時のコツは?

矢崎:文章を繋ぐ言葉が出てきたら、繋ぐことを諦めてそこでちょん切るということをやっています。「〜で」とか「〜ので」が出てきたら、そこで「〜です」「〜でした」とぶつ切りにしてみましょう。

堀越:セッション1の「タイトル」の話と近いんですが、私はSlackだと「今から自慢をします!すごいって言ってください!」とか、「今から質問をします」とか、「提案をします」みたいに、今から何の話をするのかということを最初に相手に投げちゃいますね。そうすると相手も「お、自慢話が来るんだな」という心の準備ができるかなって。

Q. 文章に関するお勧めの書籍は?

矢崎:これは「日本語スタイルガイド(第3版)」、通称緑の本ですね。お勧めします。

堀越:私もテクニカルライターとしてLINEに入るまで、この書籍のことは知らなかったんですけど、テクニカルライターの皆さんはこの本を参考にしながら、文章を書いたり、直したり、迷った時の指標にしているそうです。

矢崎:辞書みたいに使う本です。一通りタイトルを眺めておいて、あとで必要に応じて探す、みたいな使い方をします。とても役に立ちます。

Q. テクニカルライターのチームにリードエンジニアがいるのはなぜ?

堀越:ドキュメントを書く上で、書く環境を整備したり、サイト自体を改善しドキュメントを見やすく分かりやすくしていくためには、ライターの力だけじゃなくてエンジニアの力も必要なんですね。たとえば、マークダウンで書いた注釈や表などが見やすく表示されるようにする、あるいはデプロイの時間を短縮することでより素早くドキュメントを直せるようにする、英語はあるけど中国語はないドキュメントで中国語ページの代わりに英語のページを出してあげる、などなど。リードエンジニアが「ドキュメントをより良くしよう」と自ら提案をして、改善していってくれるのは、我々のチームにとってすごく重要なことです。なのでリードエンジニアがいなくなったら困りますね。

矢崎:VuePressを飼い慣らすのを、ライターはやりたくない!エンジニアいないとつらい!

堀越:そうそう。我々のLINE Developersサイトって、約1年前くらいに、ドキュメントの内容はそのままで、裏側がMiddlemanからVuePressに移行してるんですよね。

矢崎:その時にリードしてくれたエンジニアが書いた、VuePress移行に関するブログ(LINE Developers site: From Middleman to VuePress)もありますね。

Q. テクニカルライターの評価基準は?

矢崎:テクニカルライターの評価は難しいのですが、「これができたらレベルが上がるよね」のような成長の基準はあります。たとえば開発の人たちが書いた仕様書を見て、それをAPIリファレンスやドキュメントに仕上げるという仕事があったとき、もらった仕様書をそのまま綺麗な文章にできる人が、初心者テクニカルライターです。

堀越:うんうん。分かります。

矢崎:その先のレベルだと、対象のAPIを使う前に準備しなければいけないことが分かるようになってきます。あらかじめやっておかなければいけないことを正しく、誰にも指摘されずに書ける、理解できる、そして、その流れ自体もきちんと書けるようになる。さらに「実はこんなことにも気をつける必要がある」「あの機能と似ているけど、こういうところが違う」といったような、「製品全体の中でその機能がどんな役割を果たすのか」ということが分かった上で書けるようになると、また一歩先に進めるんじゃないかなと思いますね。なので、あなたはここまでできているから、次はここちょっと気をつけてみてというように、次のレベルへ成長できるようにアドバイスをしたりします。

堀越:このAPIを使う前に、そもそもAとBとCは済ませているはずだ、という前提があったりするので、単に「このAPIについてドキュメントを書いてください」と頼まれたとしても、「じゃあAとBとCの話も手前に書いてあげないとな」という風に自分で気づけると、初心者テクニカルライターを抜けてもう一歩上!という感じになりますね。

チャットやハッシュタグでリアルタイムのコミュニケーション

ちなみにセッション1の終了後は、こんな愉快なやりとりも発生しました。

堀越:矢崎さん、喋ってる間は見られなかったと思うんですけど、Twitterのハッシュタグ(#LINE_TWM)がすごく盛り上がってましたよ!

矢崎:ほんとですか?!それどこで見るんですか?あ、Twitterか!

堀越:Twitterのハッシュタグなので、Twitterで見てください!

2人ともツボに入ってしまっていい笑顔です。



ミートアップはオンラインでの開催なので、登壇者である我々には参加者の姿は見えず、肉声も聞こえません。でもYouTube Liveのチャットや、Twitterのハッシュタグ(#LINE_TWM)でみなさんからいただいたリアルタイムの感想やコメントは、どれもとてもあたたかく、我々だけでなくみんなでイベントを作っている感じがして本当に励みになりました。難しい質問にどう答えるか悩む我々を参加者のみなさんが応援くださったり、Q&Aで紹介した「お勧めの書籍」をみなさんが次々と購入している様子が見えたり、「話を聞くだけ」の一方的なイベントではなく、双方向のコミュニケーションができる参加型のミートアップにできたのはみなさんのお陰です。ありがとうございました!

開催後のアンケートでも、ミートアップの満足度は「期待以上に面白かった」と「面白かった」が99%を占めました。「次はこんな話も聞きたい!」というコメントもたくさんいただいたので、次回以降のセッションに反映していきたいと思います。ご期待ください!

次回のLINE Technical Writing Meetupは4月15日(木)に開催

さて、次回のLINE Technical Writing Meetup vol.2は、既に日程(4月15日)も決定して、connpassにて参加申し込みを受付中です!

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

次回はこんな内容を予定しています。vol.1とvol.2は連続した内容ではなく、どの回から参加しても、どのセッションだけ見ても、問題なく楽しめますので、今後もご都合がつきましたらぜひご参加ください。

  • セッション1:説明の順番も大事な情報
    • 矢崎 誠 / @yazakimakoto / LINE株式会社 テクニカルライター
    • 説明したいことを思いつくままに書いてみたら、思いのほか多くなってしまい、書き終わってみたら分かりにくいって感じたり、言われたりしたことはありませんか。実は、説明の順番も読者にとっては大切な情報です。どんな順番で説明していくとうまく伝わるのか、テクニカルライターが気にしているポイントを紹介します。
  • セッション2:いちばん良い一行を見つける近道
    • 堀越 良子 / @mochikoAsTech / LINE株式会社 テクニカルライター。元インフラエンジニア。ねこが好き。
    • 「ここの説明、いまいち分かりにくいから直したいんだけど、どうしようかな」と悩みながら、書き足したり、消したり、少し言い回しを変えたり、前後を入れ替えたり、いやいややっぱりさっきの方がよかったかも、と元に戻したり…いちばん良い一行を探してあーだこーだと長時間悩んでしまった経験はありませんか?いちばん良い一行を見つけるための近道をテクニカルライターが教えます。


テクニカルライターという仕事に興味をもったら…

最後にちょっとだけ求人の話をさせてください。LINE Technical Writing Meetupに参加して、「テクニカルライターって面白そう」「ちょっと興味あるな」と思った方は、ぜひこちらの採用情報をご覧いただき、矢崎さんへお気軽にお声がけください。Zoomでのカジュアル面談なども可能です!

「テクニカルライター / Japanese documents」の求人詳細