2021年11月10日・11日の2日間にわたり、LINEのオンライン技術カンファレンス「LINE DEVELOPER DAY 2021」が開催されました。特別連載企画「DEVDAY21 +Interview」では、登壇者たちに発表内容をさらに深堀り、発表では触れられなかった関連の内容や裏話などについてインタビューします。今回の対象セッションは「LINEの開発者向けドキュメントを支える『テクニカルライティング』の専門チーム」です。
プロダクトを多くの開発者に使ってもらうには、よいプロダクトであることと同時に、使い方がすぐに分かるドキュメントが用意されていることが重要です。LINEには、多様なドキュメントを同時に、かつ多言語でメンテナンスし続けているテクニカルライターと、Webサイトの開発を担う専任のフロントエンドエンジニアが在籍するテクニカルライティングの専門チームがあります。今回は、テクニカルライターである堀越良子と、フロントエンドエンジニアのロッサ ロマンに、チームの仕事内容と専門チームが提供できる価値について聞きました。
初心者が読むことも想定しながらドキュメントを執筆
――テクニカルライティングの専門チームが立ち上げられた経緯を教えてください。
堀越：もともとLINE APIを使って開発を行っている社内外のエンジニアから問い合わせを受け付ける、サポートのためのチームがあり、その中にドキュメントを作成するためのチームもありました。複数の人から同様の内容の質問があるといったとき、あらかじめドキュメントを作成して公開した方が効率的だったためです。
それでサポートチームには、問い合わせに対応するメンバーとドキュメントを執筆するメンバーがいましたが、そのうちのドキュメンテーション部分が切り離されてテクニカルライティングの専門チーム、現在のDeveloper Contentチームが立ち上がりました。
現在はライティングを担当するメンバーが6名で、エンジニアであるロッサ ロマンを含めた7名のチームで活動しています。
ロマン：チームが分かれたのは2018年の秋頃です。その時期に僕を含めた何人かが入社してチーム規模が大きくなったことで、ドキュメンテーションが独立することになりました。
――テクニカルライターとしてドキュメントを執筆する際、どんなことを意識しているのでしょうか。
堀越：ドキュメントを執筆する際は、対象となる機能やAPIの仕様について、ミーティング、あるいはWikiのURLを渡されるといった形でインプットを受けます。ただ仕様と実装が異なっているケースもあるため、仕様の内容だけを見て書くのではなく、極力自分たちで手を動かし、確認した上で執筆するようにしています。
また、実際にドキュメントを読む人たちは、何かを実装することが目的なはずなので、執筆する際は読者の目線を意識しながら作業を進めています。
初心者の人でもわかりやすいように書くことも、ドキュメントを作成する際に意識していることの1つです。たとえば初心者の人が読むと誤解してしまう文章になっている、あるいはAという単語が出てくるけれど、Aについてそれまで全く触れていないので、初心者にはわからないといったことが考えられます。我々には読む人の理解度はコントロールできないため、初心者の人が読むことも想定しながら書くようにしています
――Developer Contentチームでテクニカルライターとして仕事をしていく上で、プログラミングスキルは必須でしょうか。
堀越：「LINE Developersサイト」にあるドキュメントを読み、LINEのAPIを使って実装してくださいと言われたときに、内容を理解し、実際に手を動かして何かを作れるといったレベルのスキルは必要だと考えています。
エンジニアから話を聞き「これがこうなってああなります」と説明されたときに全くわからないという状態だと、なかなか厳しいですよね。エンジニアが話していることが分かる程度の基礎知識は必要だと思いますし、その基礎知識は実際にコードを書いていく過程で少しずつ身についてくることが多いと思います。そのため、仕事でも個人としてでも構わないので、エンジニアリングの経験が何かしらあった方がいいと思っています。
ドキュメントやサポートまで含めてプロダクト
――先ほど仕様のインプットを受けるというお話がありましたが、エンジニアとのコミュニケーションで意識していることはありますか。
堀越：テクニカルライターがいるメリットの1つは、エンジニアがドキュメントを作成する必要がなくなり、コードを書くことに専念できる点だと考えています。そこで意識しているのは、エンジニアの工数を使いすぎないことです。
エンジニアが自分自身で書けば1時間で済むのに、テクニカルライターに頼むとヒアリングとドキュメントのレビューで3時間かかってしまうということになれば、テクニカルライターが存在する意味がなくなってしまいます。
ただ、どうしてもエンジニアに質問しなければならないケースはあります。そのときは「この仕様はどうなっているんですか？」といった形で聞くのではなく、いくつかのパターンの仕様とそれに合わせた文章を作成し、「どれですか？」と聞くようにしています。これならエンジニアは「これです」と一言で返せばよく、仕様の説明にかかる時間を省くことができます。
一方でLINEのエンジニアは、仕様をきちんと残さなければならないと意識している人が多いので、APIのリファレンスなどもエンジニア自身でWikiにまとめてあり、質問しなくても分かることが少なくありません。
Developer Contentチームとエンジニアのチームの気持ちの距離が近いところも、LINEのよさだと感じています。ドキュメントを書くために質問したとき、「そっちで適当にやって」などと言われることはまったくなく、「それはこういう使い方をしてもらう前提なので、こういう作りにしています」と、背景まで含めて説明してもらえるなど、エンジニアもドキュメントの大切さを理解した上で私たちの質問に答えてくれています。
実は先日も、エンジニア側から「我々はAPIだけを提供しているのではなく、ドキュメントやサポートまで含めてプロダクトだと思っているので、もっと協力していこう」と申し出があったんですよね。そうした姿勢で私たちテクニカルライターと向き合ってもらえるのは、すごくありがたいなと思いました。
外部のユーザーと社内のテクニカルライターの両方を満足させたい
――ロッサ ロマンさんの役割を教えてください。
ロマン：フロントエンドエンジニアとしてLINE Developersサイトの開発を担当しています。
いくらドキュメントがわかりやすく書かれていても、それを載せているWebサイトが使いづらければ読む人は幸せになりません。そのため、LINE Developersサイトでは使いやすいサイトにするために様々な工夫をしたり、機能を提供したりしています。
たとえばWebサイトのレスポンスです。 VuePressを使って開発しているので、LINE DevelopersサイトはSPA（single page application）としてレンダリングされていて、ページ間をサクサクと移動できます。さらにElasticsearchを利用した、全文検索の機能もあります。フィードバックフォームもあり、ドキュメントを読んだ人がコメントを書いて送信できるようにしています。私たちは投稿していただいたフィードバックを参考にしながらWebサイトを改善しています。
テクニカルライターのチームに、なぜエンジニアがいるのかと不思議に思うかもしれません。ただイタリアンレストランに行けば、ピザやパスタと言ったイタリア料理はありますが、寿司を注文することはできないでしょう。専門が違うので当然です。
テクニカルライターとエンジニアの関係もまったく一緒です。テクニカルライターに使いやすいWebサイトを開発してとはお願いできないでしょう。なのでエンジニアが必要なのです。
堀越：仕事をしていると、テクニカルライターの本来の仕事であるドキュメントを書くということ以外に、細かい仕事って出てくるんですよね。
たとえばページのデザインが少し崩れているとか、ページの表示にすごく時間がかかるといった不具合があり、それに対応しなければならないといった場面です。そのときチーム内にエンジニアがいることで、テクニカルライターはライティングに専念し、エンジニアであるロマンさんはWebサイトの問題解決や使い勝手の向上に集中することができて、と役割分担ができます。これはすごくありがたいところです。
また、仮に外部にWebサイトの開発を依頼するといった場合、そもそも何をお願いするのかを自分たちで定義できなければならないと思います。しかし私たちはチーム内にロマンさんがいるので、解決策はわからないけれどこういうもやもやがある、どうにかできないか、といった頼み方ができます。これもすごく大きなところです。
ロマン：僕が開発しているLINE Developersサイトにアクセスしていただいている、外部のユーザーの方に満足してもらいたいのはもちろんですが、同じチームで働いているテクニカルライターの方たちも僕にとっては大切なユーザーです。この双方のユーザーに満足してもらうことが僕の仕事です。
システムの改修を重ねてドキュメントの改善ページを向上
――セッションでドキュメントを改善するペースが上がっているというお話がありました。その背景には、どのような工夫があったのでしょうか。
堀越：原稿を書いてからWebサイトにリリースするまでには、いくつかのステップがあります。そのステップの待ち時間をロマンさんが少しずつ改善してくれたことで、改善のペースが上がったと感じています。
ロマン：まずテクニカルライターは自分のパソコンでドキュメントを書き、その内容をローカルで確認します。その後GitHubに原稿をプッシュすると、自動的に検証向けの環境であるサンドボックスにデプロイされます。これによってほかの人が確認できるようになり、問題がなければマスターにマージしてリリース作業に入ります。従来は、このそれぞれのステップで時間がかかっていたんですね。
たとえばGitHubにプッシュしてから1時間待たされるということになれば、その後の作業に大きな影響が出ますよね。そこで、この待ち時間を減らすために様々な工夫を行ってきました。 現在では5分程度でサンドボックスに反映されるようになっています。
――LINE Developersサイトの開発で印象に残っていることはなんですか。
ロマン：LINE Developersサイトでは、静的サイトジェネレーターとして以前はMiddlemanを利用していましたが、それをVuePressに移行したことが印象に残っています。
まず、コンテンツが大量にあるので、それをVuePressに沿ったフォーマットへ変更していくのが大変でした。VuePressへの移行には準備だけで数ヶ月かかっていたので、一度すべてのコンテンツをVuePressへ移行したとしても、移行準備をしている間に、運用中のMiddleman側ではどんどんコンテンツが更新されていきます。そのため準備中のVuePress側で定期的にコンテンツを最新版へ更新する必要がありました。コンテンツの更新を自動化するためのスクリプトも用意していましたが、コンテンツが多いことによってフォーマットのケースも山ほどあり、自動化で全てのケースに対応するのが大変でした。
また、コンテンツの量が多いことにより、最初はVuePressのビルド時間がとても遅かったです。1時間以上待ってもビルドがまだ完了しないことがありました。そうなると、先ほど言ったように、ライターさんの作業に悪影響を与えてしまい、ドキュメントの更新がやりづらくなります。そこでビルドを言語ごと（日本語・英語・中国語）に分割すること、そしてそのビルド処理を並列で行うことによって、ビルド時間を5分程度まで短縮させることができました。
こういうふうに様々な面で工夫してきた結果、最終的にVuePressへ無事に移行することができました。
――最後に、今後取り組みたいことについて教えてください。
ロマン：テクニカルライターが作業しやすい環境を整えることにもっと取り組んでいきたいですね。また自動化できる部分があれば、それにも取り組みたいです。たとえば定期的に発生するタスクで、現状は手動で対応しているステップを自動化するなどといったことが実現できればと思っています。また内部的なサーバーの整理やサーバーの更新などといった改善も進めていきます。
堀越：あるゴールに対して1から5までのステップがあるとしたとき、以前は2と4が欠けているといったように、必要なドキュメントが不足しているケースがありました。そのため、2と4の知識を自分で埋められる人はゴールまで行けるけれど、それができない人はゴールに辿り着けないといったことが起こっていたんですね。
そうした状態を改善し、現在は1から5までのドキュメントがそろった状態にできたと思うのですが、一方でそもそも1に辿り着けない人のために誘導するためのドキュメントを書いたり、1と2の幅が広いので1.5となるドキュメントを用意するといった工夫も必要だと感じています。そうした取り組みを進めて、初心者の方が読んでもわかるように、深い情報を求める方が読んでもそのニーズに応えられるように、より親切なWebサイトを目指していきたいと思います。
採用情報
LINE株式会社では一緒に働くメンバーを募集しています！
今回のインタビューと関連する募集ポジションはこちらです。