ライターが使いやすいプラットフォームを提供　「テクニカルライティング」チームにおけるエンジニアのお仕事

エンジニアをアサインしたほうがいい理由

ロッサ・ロマン：では今から、エンジニアの視点からお話ししていきたいと思います。先ほど、テクニカルライティングチームがあったほうがいい理由が、たくさんあったと思うのですが、今からそのテクニカルライティングチームにエンジニアをアサインしたほうがいい理由について話していきたいと思います。

アジェンダはご覧のとおりで、エンジニアをアサインしたほうがいい理由と、私がエンジニアとして日々どのようにライターさんのサポートをしているかについて、話していきたいと思います。

では、エンジニアをアサインしたほうがいい理由です。先ほど話していただいたとおりなのですが、ライティングは簡単ではありません。書かなきゃいけないコンテンツが多いですし、わかりやすい文章にするためにはちゃんとプロフェッショナルな技術者がいると思います。

もちろん、ドキュメンテーションを読む人から見ると、わかりやすく書かれたドキュメンテーションが一番大事だと思いますが、それがすべてではありません。そのドキュメンテーションを読むユーザーから見たUXについて、もう少し話ししていきたいと思います。

想像していただきたいのですが、どんなにわかりやすい文書、どんなにわかりやすいドキュメンテーションがあったとしても、そのドキュメンテーションが使いづらいWebサイトに載っていると、読む人からするとツライです。なので、わかりやすい文書だけでなく、使いやすいサイトも大事だと思います。イメージはこのとおりですね。

では、LINE Developersサイトで言いますと、本当に使いやすいサイトになっているかは、実際にみなさんに使ってもらって最終的に判断してほしいのですが、一応使いやすいサイトにするためにさまざまな機能を提供しています。

まず、LINE DevelopersサイトはVuePressで開発されていて、VuePressを使うことによってページがサクサク動いて速いです。多言語にも対応しています。

そしてこちらは全文検索です。コンテンツが多いので、探しやすさも大事で、全文検索を提供しています。ここではElasticsearchを使っています。

そして次はフィードバックフォームです。ドキュメンテーションを読む人が実際にコメントを書いて送信できます。私たちは実際にそのフィードバックを読んで、それを参考にサイトを改善していきます。

こちらはMessaging APIのリファレンスのスクショとなりますが、こちらもリッチなUIを提供していて、例えばコードサンプルのタブUIなどがあります。今ここでは映っていないのですが、一部のMessaging APIを実際に試せるAPI Playgroundといった機能もあります。

そして日々ニュースも配信しています。ニュースもまた探しやすさが大事で、こんな感じでタグでフィルタリングするような機能を提供しています。

専用のエンジニアが必要な理由

ではまた、テクニカルライターというプロフェッショナルの話に戻りたいと思います。まず少し違う場面を想像してほしいのですが、イタリアンレストランへ行くとします。イタリアンレストランに行ったら、当然ピザだったりパスタだったり、こういったイタリアン料理があるかと思います。なのでこういった料理を作る専門家、イタリアンのシェフがいるわけですね。なので、当然イタリアン料理はあるのですが、おすしは注文できないですよね。これは専門が違うという話になります。

実はテクニカルライターもまったく一緒です。テクニカルライターは文書を書く専門家なので、いきなり「じゃあ使いやすいWebサイト開発してね」とは、なかなかお願いできないでしょう。なのでエンジニアが必要です、というお話でした。

どのようにライターをサポートしているのか

では今からはもう少し具体的に、私はエンジニアとして、どのようにライターさんをサポートしているかについて話をしていきたいと思います。

まずエンジニアの役割についてです。私から見ると、ユーザーは2種類います。1つ目のユーザーは、先ほど話したとおり外部の開発者で、LINE Developersサイトを見ているユーザーです。そのユーザーに、使いやすいサイトを提供しようとしています。ではもう1種類のユーザーはなにかと言いますと、まさにチーム内のテクニカルライターとなります。

私から見て、なぜテクニカルライターがユーザーとなっているかというと、テクニカルライターが文書を書いたり、その見た目を確認したり、リリースしたりするわけですね。こういった作業をスムーズにするためのプラットフォームが必要となります。

そのプラットフォームを私が開発したり提供したりしているので、そう考えると、ライターはそのプラットフォームを使うユーザーとなりますね。そしてライターさんの日々のサポートもありますが、これについてはまた後でお話しします。

ライターに提供しているプラットフォーム

まず、ライターに提供しているプラットフォームの話ですが、最初はローカルセットアップです。自分のローカルパソコンに環境をインストールしなきゃいけませんが、LINE Developersサイトで言いますと、これが簡単です。

ちょっと省略した手順になりますが、簡単に言うと、git cloneでソースコードをダウンロードして、npm installでパッケージをインストールして、そして「./run.sh」と叩けば、このようにローカルホストでWebサイトが立ち上がります。このローカル環境でWebサイトの見た目を確認できます。あとはMarkdownを書くだけで、ローカルマシンで見た目を確認できます。

Markdownについてもう少しお話ししていきたいと思います。ご存じかと思いますが、Markdownだと、簡単なドキュメントのフォーマッティングが実現できます。例えばヘッダーだったり、簡単な表だったり、箇条書きだったり、ベーシックなフォーマッティングができます。

ただそのベーシックなMarkdownで機能が足りない場合はどうするかということを今から説明します。まず、先ほど話したとおり、LINE DevelopersサイトではVuePressを使っていて、VuePressがMarkdownをサポートしています。

他にもVuePressを採用した理由があります。例えば多言語対応などです。あとVuePressはVue.jsで書かれているので、個人的にうれしいですし、社内もけっこうVue.jsを使っています。そしてサイトをレンダリングすると、SPA、シングルページアプリケーションのサイトができあがるので、サクサク動いて速いです。

Markdownの機能

また、Markdownの機能をVue.jsコンポーネントで拡張できます。ここは大事なのでもう1回言います。Vue.jsのコンポーネントを使って、Markdownの機能を拡張できます。ここはとっても興味深いので、今からもう少し詳しくお話ししていきたいと思います。

Markdown拡張ですが、2つの例を挙げます。1つ目の例はAPIリファレンスです。こちらもまた、Messaging APIリファレンスの一部のスクショとなります。

このUIだけで言いますと、ただのベーシックMarkdownで実現できないUIコンポーネントがいくつか入っています。例えば2カラムのレイアウトや、パラメーターをフォーマッティングするテーブルや、タブUIのコードサンプルなど、いろいろ入っています。

このUIの後ろにどういうMarkdownがあるかと言うと、こんな感じです。ご覧とおり、Markdownコードではあるのですが、中にはいくつかVue.jsのコンポーネントが入っています。例えば2カラムを実現するReferenceWithCodeや、左側の文章が入っているReferenceContentというコンポーネントがあります。

また、右側のコードサンプルはReferenceCodeに入っていますし、またその中にTabsというタブUIを実現するコンポーネントもあります。

最後に、Messaging APIエンドポイントのパラメーターをフォーマッティングできるパラメーターテーブルもあります。これらはいろいろ社内でカスタムで作ったコンポーネントとなります。

コンポーネントが多いのですが、実はそれぞれのコンポーネントはそんなに複雑なことをしていないですね。だいたいフォーマッティングぐらいです。なので、次の例にいきたいと思います。次の例では、もう少し複雑なMarkdown拡張の例を挙げていきたいと思います。

次の例は、Messaging APIのスタンプについてです。ご存じのとおりLINEアプリではスタンプを送信できます。で、同じくMessaging APIを使ってチャットボットを開発した場合でも、チャットボットからスタンプを送信できます。

例えばチャットボットからブラウンのスタンプを送信したい場合は、そのスタンプのIDを指定しなきゃいけません。具体的にpackageIdとstickerIdなどのIDがあるのですが、こういうIDを指定する必要があります。

なので、例えばブラウンのスタンプを送信したい場合は、まずチャットボットの開発者がそのIDを探さなくてはいけません。昔は、こういったかたちでPDFファイルを提供していました。PDFの中にスタンプの一覧がありますと。ただ、これは実はいろいろな問題があります。

まず、チャットボットの開発者がそのPDFをダウンロードしてIDを探さなくてはいけません。またPDFの中には複数のページがあるので多少使いづらく、探しづらいですね。また私たち提供する側から見ると、そのPDFの更新もなかなか面倒なので、あまりよろしくない状態です。

なのでPDFではなく、もうサイト上でスタンプの一覧を出したほうが良くない？　という話になりまして、ジャジャーン！こういうふうにページを改善して、もうページ上でスタンプの一覧を出すことになりました。このスタンプのページ上のUIはどのようにして実現できたかということを、今から説明します。

まず社内で、そもそもMessaging APIでどういうスタンプが使えるのかがわかるスタンプのリスト、IDのリストを探さなきゃいけませんでした。次はそれぞれのIDと紐づいている画像のデータを集めなくてはいけませんでした。こういったデータを集めたうえで、またフロントエンド開発を行なって、このようなUIを開発していきました。

データを集める段階だけでも、さまざまなスクリプトを書いて開発してきたわけですが、UIの開発、こちらに映っているスクショのUIのコードだけで言いますと、このくらいフロントエンドのソースコードがあります。けっこう大きいVue.jsのコンポーネントになっていますね。

いろいろ開発をしてきましたが、この話がMarkdown拡張やライターとどのように関係しているのかと言うと、ライターがMarkdownを使って書いているんですね。左側の複雑なソースコードを、ライターさんはどのように使うかというと、簡単です。この1行だけです。ライターがその1行書くだけで、このようなリッチなUIを出せます。

開発でがんばった結果、ライターから見ると、1行書くだけでリッチなUIを出せるようになりました。ライターから見るととても簡単です。

同じチームにいることのメリット

ここまでで、たくさん開発をして、たくさんプラットフォームを提供した話をしてきたと思います。実はここまでの話だと、自分が同じチームにいなくて、例えば別のチーム、開発の部署などに依頼しても、こういったプラットフォームの開発はしてもらえたかもしれません。

ただそれだけでなく、私は同じチームにいる、日々傍にいることによってメリットがあると思っています。それについては今から話していきたいと思います。

日々のサポートですが、先ほど話があったとおり、さまざまな環境があります。見た目を確認できるローカルホストの環境やSandboxなど、この環境でつまずいたり、どこかで引っ掛かったら、僕はすぐ傍にいるのでサポートできます。なんかSandboxが更新されない、ローカルホストが更新されない、見た目が確認できないなどと困ったときにすぐにサポートできるのです。

そして日々一緒に仕事することによって、やはりライターのニーズがわかってきます。例えば「Sandboxのビルドが成功したかわからない」「リンク切れが起きていないか心配だよね」など、こういった悩みがある場合は、先ほど話があったとおり、例えばプルリクエストチェックを導入できます。私がそういうニーズを把握しているので、自分から提案して、こういった機能を実現できます。

そしてドキュメントをリリースする際、例えば「見た目が想像した見た目と違う」「Jenkinsが動かない」「更新できない」「リリースできない」などといった困った場合にも、僕がすぐサポートできます。

そして、もし社内のサーバーが使えなくなったり、ソフトの更新があったり、Vue.jsやVuePressの新しいバージョン出たりしても、こういったシステム部分も僕が自ら対応できます。そうすると、ライターがシステム周りを気にしなくてよくて、安心してライティングに集中できます。

そしてライターさんは、よく社内から急な依頼をされたりします。例えば、急にこのドキュメント更新してください、急にこのニュースを出してほしいです、などといったリクエストが定期的にくるんですね。

この場合「あ、このニュース出したいけどこのUIコンポーネントがない」などとライターが困ったら、僕がまた傍ですぐサポートできて、すぐその必要なUIのコンポーネントを開発して提供できます。

やはりこういった対応は、同じチームで傍にいないと、なかなかできないかなと思います。別のチーム、別の部署に依頼するとしても、対応が遅れると思います。

エンジニアとしてのメリット

もう少し個人の話をしますと、個人的にもライティングチームにいることによって、メリットがあります。単純にエンジニア同士ではなく、ライターさんと一緒に働くことによって、違う視点で見たり、刺激を得たりできるので楽しいです。そして外部のユーザーもライターさんもサポートしているので、けっこう責任を感じていて、そこに仕事のやりがいを感じています。

そしてテクニカルライティングのチームには、エンジニアとして僕しかいないので、自由に働けて、個人的にそれが好きです。

エンジニアのお話は以上となります。では、まとめでもう1回堀越さんに戻ります。お願いします。

毎月LINE Technical Writing Meetupを開催

堀越良子氏：それでは最後に本日お話ししてきたことのまとめです。プロダクトを多くの開発者に使ってもらうには、良いプロダクトであることと同時に、良いドキュメントがあるということがとっても重要です。

そしてテクニカルライティングのチームを社内に持つと、ドキュメントの品質が上がる、開発者が開発に専念できるなど、さまざまな良いことがあります。それからチームを作る時には、テクニカルライターだけでなく、エンジニアもチームに含めることをお勧めします。

以上「LINEの開発者向けドキュメントを支える『テクニカルライティング』の専門チーム」というセッションでお伝えしてきた3つの内容のまとめでした。

今日の話を聞いて「テクニカルライターという仕事についてもっと詳しく聞きたい」あるいは「テクニカルライターと働くエンジニアのポジションに興味がある」と思ったら、私やロマンさんとのカジュアル面談も常時受け付けています。お気軽にご連絡ください。

また、テクニカルライティングに関するお話は、毎月開催しているLINE Technical Writing Meetupでも継続的に行なっています。今日のセッションを聞いて「テクニカルライティング自体に興味を持った」という場合は、こちらのMeetupもぜひご参加いただければと思います。

それでは「LINEの開発者向けドキュメントを支える『テクニカルライティング』の専門チーム」というセッションを終わります。本日はご参加いただきありがとうございました。