2024.10.10
将来は卵1パックの価格が2倍に? 多くの日本人が知らない世界の新潮流、「動物福祉」とは
提供:LINE株式会社
リンクをコピー
記事をブックマーク
ロッサ・ロマン:では今から、エンジニアの視点からお話ししていきたいと思います。先ほど、テクニカルライティングチームがあったほうがいい理由が、たくさんあったと思うのですが、今からそのテクニカルライティングチームにエンジニアをアサインしたほうがいい理由について話していきたいと思います。
アジェンダはご覧のとおりで、エンジニアをアサインしたほうがいい理由と、私がエンジニアとして日々どのようにライターさんのサポートをしているかについて、話していきたいと思います。
では、エンジニアをアサインしたほうがいい理由です。先ほど話していただいたとおりなのですが、ライティングは簡単ではありません。書かなきゃいけないコンテンツが多いですし、わかりやすい文章にするためにはちゃんとプロフェッショナルな技術者がいると思います。
もちろん、ドキュメンテーションを読む人から見ると、わかりやすく書かれたドキュメンテーションが一番大事だと思いますが、それがすべてではありません。そのドキュメンテーションを読むユーザーから見た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の機能を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の開発者向けドキュメントを支える『テクニカルライティング』の専門チーム」というセッションでお伝えしてきた3つの内容のまとめでした。
今日の話を聞いて「テクニカルライターという仕事についてもっと詳しく聞きたい」あるいは「テクニカルライターと働くエンジニアのポジションに興味がある」と思ったら、私やロマンさんとのカジュアル面談も常時受け付けています。お気軽にご連絡ください。
また、テクニカルライティングに関するお話は、毎月開催しているLINE Technical Writing Meetupでも継続的に行なっています。今日のセッションを聞いて「テクニカルライティング自体に興味を持った」という場合は、こちらのMeetupもぜひご参加いただければと思います。
それでは「LINEの開発者向けドキュメントを支える『テクニカルライティング』の専門チーム」というセッションを終わります。本日はご参加いただきありがとうございました。
LINE株式会社
関連タグ:
2024.10.29
5〜10万円の低単価案件の受注をやめたら労働生産性が劇的に向上 相見積もり案件には提案書を出さないことで見えた“意外な効果”
2024.10.24
パワポ資料の「手戻り」が多すぎる問題の解消法 資料作成のプロが語る、修正の無限ループから抜け出す4つのコツ
2024.10.28
スキル重視の採用を続けた結果、早期離職が増え社員が1人に… 下半期の退職者ゼロを達成した「関係の質」向上の取り組み
2024.10.22
気づかぬうちに評価を下げる「ダメな口癖」3選 デキる人はやっている、上司の指摘に対する上手な返し方
2024.10.24
リスクを取らない人が多い日本は、むしろ稼ぐチャンス? 日本のGDP4位転落の今、個人に必要なマインドとは
2024.10.23
「初任給40万円時代」が、比較的早いうちにやってくる? これから淘汰される会社・生き残る会社の分かれ目
2024.10.23
「どうしてもあなたから買いたい」と言われる営業になるには 『無敗営業』著者が教える、納得感を高める商談の進め方
2024.10.28
“力を抜くこと”がリーダーにとって重要な理由 「人間の達人」タモリさんから学んだ自然体の大切さ
2024.10.29
「テスラの何がすごいのか」がわからない学生たち 起業率2年連続日本一の大学で「Appleのフレームワーク」を教えるわけ
2024.10.30
職場にいる「困った部下」への対処法 上司・部下間で生まれる“常識のズレ”を解消するには
2024.10.29
5〜10万円の低単価案件の受注をやめたら労働生産性が劇的に向上 相見積もり案件には提案書を出さないことで見えた“意外な効果”
2024.10.24
パワポ資料の「手戻り」が多すぎる問題の解消法 資料作成のプロが語る、修正の無限ループから抜け出す4つのコツ
2024.10.28
スキル重視の採用を続けた結果、早期離職が増え社員が1人に… 下半期の退職者ゼロを達成した「関係の質」向上の取り組み
2024.10.22
気づかぬうちに評価を下げる「ダメな口癖」3選 デキる人はやっている、上司の指摘に対する上手な返し方
2024.10.24
リスクを取らない人が多い日本は、むしろ稼ぐチャンス? 日本のGDP4位転落の今、個人に必要なマインドとは
2024.10.23
「初任給40万円時代」が、比較的早いうちにやってくる? これから淘汰される会社・生き残る会社の分かれ目
2024.10.23
「どうしてもあなたから買いたい」と言われる営業になるには 『無敗営業』著者が教える、納得感を高める商談の進め方
2024.10.28
“力を抜くこと”がリーダーにとって重要な理由 「人間の達人」タモリさんから学んだ自然体の大切さ
2024.10.29
「テスラの何がすごいのか」がわからない学生たち 起業率2年連続日本一の大学で「Appleのフレームワーク」を教えるわけ
2024.10.30
職場にいる「困った部下」への対処法 上司・部下間で生まれる“常識のズレ”を解消するには