LINEヤフー Tech Blog

LINEヤフー株式会社のサービスを支える、技術・開発文化を発信しています。

エンジニアとテクニカルライターが連携するドキュメント作成プロセス紹介

こんにちは。Messaging APIを開発しているソフトウェアエンジニアの奥薗と、LINE Developersサイトで開発ドキュメントを書いているテクニカルライターの銭神です。みなさんの開発の現場では、どのようにしてドキュメントを書いているでしょうか。この記事では、私たちの組織において、ソフトウェアエンジニア(以下「エンジニア」といいます)とテクニカルライターがどのように連携して社外向けのドキュメントを書いているかを紹介します。

私たちのチームについて

エンジニアとテクニカルライターの協業についての話をする前に、私たちがそれぞれどのようなチームで、どのようなプロダクトを担当しているかを説明します。なお、各セクションのタイトル名の後ろに、どちらが執筆したかをカッコ書きで示しています。

Messaging APIの開発チーム(奥薗)

まずは、Messaging APIの開発チームについてです。Messaging APIとは、LINEプラットフォームが提供している開発者向けのサービスのひとつです。Messaging APIを用いることで、LINEでユーザーにメッセージを送信したり、ユーザーのアクションに応じたWebhookを通して、自動的に応答メッセージを返したりすることができます。また、トークルームに特別なメニューを設置して、その動作をカスタマイズすることもできます。

LINE公式アカウント

LINEプラットフォームでは、ビジネスオーナーやクリエイターの方々がLINEアプリを通してさまざまな双方向のコミュニケーションサービスを実現できるよう、このMessaging APIを提供しています。これにより、個人が開発するチャットボットや、サードパーティ製のCMSなど、さまざまなものに応用することができます。

Messaging APIの開発チームでは、以上のようなことを実現するためのAPIの開発に携わっています。

ドキュメントの担当チーム(銭神)

さて、このMessaging APIは、私たちの会社内はもちろん、外部の企業や開発者の方々にも利用していただいています。Messaging APIを利用するためには、機能についてのドキュメントやリファレンス、あるいは新機能のリリース情報などが必要になるのですが、これらはLINE Developersサイトというところで公開しています。

銭神が所属するDev Contentチームでは、このLINE Developersサイト上で、Messaging APIをはじめとして、LINEログインやLINE Front-end Framework(LIFF)、LINEミニアプリなどさまざまな製品のドキュメントを書いています。例えば、開発者の方が「自分たちのウェブサービスを、LINEアカウントでログインできるようにしたい!」と思ったときに、LINEログインのドキュメントを読むことになります。

LINE Developersサイト

私たちのチームでは、「役に立つドキュメントで開発をもっと楽しく」というミッションのもとに、日々わかりやすさを意識してドキュメントを書いています。私たちのチームの目標については、『テクニカルライターのチームで「目標」をどう決めたか』もあわせてご覧ください。

以上が、私たちのチームの紹介になります。このようなチームの中で、Messaging APIに関するドキュメントを、LINE Developersサイト上にどのように公開しているのか? ということについて、その連携のプロセスをもとに説明します。

連携のプロセス(銭神)

それでは、エンジニアとテクニカルライターがどのようにしてLINE Developers上のドキュメントを作り上げているかをお話しします。基本的な流れとしては、次のようなプロセスで作成しています。

  1. 技術仕様を決める
  2. インプットを行う
  3. ドキュメントを書く
  4. プランナーや開発者によるレビューを行う
  5. ドキュメントを翻訳する
  6. テクニカルライターによるレビューを行う
  7. ドキュメントを公開する

それぞれのステップについて説明します。

1. 技術仕様を決める

まず、Messaging APIの開発を担当しているプランナーやエンジニアの間で、機能に関する仕様を決めます。また、エンジニアが社内向けのドキュメントを書きます。

このステップでは、テクニカルライターが関わることはあまりありませんが、ときにはエンジニアから相談を受けることがあります。例えば最近では、APIのフィールド名を決めるときに、開発者にとってわかりやすい名前のアイデアを出す機会がありました。

2. インプットを行う

次に、決まった仕様について、プランナーやエンジニアからテクニカルライターに対してインプットが行われます。これは通常、ミーティングという形式で実施されます。このときに、「ドキュメントを書くために必要な情報はなにか」という観点で仕様の確認をしたり、ニュースやドキュメントの構成、スケジュールなどについて話し合います。

3. ドキュメントを書く

共有された仕様や社内向けのドキュメントをもとに、テクニカルライターがドキュメントのドラフトを作成します。このとき、仕様を読み込むのはもちろん、テスト環境でAPIの機能を検証したりします。仕様や検証の方法についてわからないことがあれば、Slackや定例ミーティングなどでプランナーやエンジニアに質問します。

ドキュメントはMarkdown形式で書いており、それをGitHub上のリポジトリで管理しています。レビューの結果は、Slackでやりとりすることもありますが、基本的にはプルリクエスト上のコメントで受け取ります。このあたりの話は、合併前に公開された『LINEの社内には「テクニカルライティング」の専門チームがあります』をご覧ください。

4. プランナーや開発者によるレビューを行う

ドキュメントのドラフトができたら、プランナーやエンジニアによるレビューが行われます。このステップでは、文章のわかりやすさというよりは、仕様や技術的な正しさについて重点的にレビューします。フィードバックがあれば、それをもとにドラフトを改善します。

5. ドキュメントを翻訳する

仕様や技術的な正しさについて問題がなければ、次はドラフトの翻訳作業に入ります。LINE Developersサイトでは日本語と英語でドキュメントを提供しており、どちらの言語もDev Contentチームで執筆を担当しています。

6. テクニカルライターによるレビューを行う

日本語と英語のドラフトが完成したら、次はテクニカルライターによって、わかりやすさや文章としての正しさについてのレビューが行われます。もちろん仕様についても重ねてレビューをしており、このステップで誤りが見つかることも稀にあります。

7. ドキュメントを公開する

テクニカルライターのレビューを通過したら、APIの機能のリリースなど、決められたタイミングでドキュメントを公開します。公開が完了したら、プランナーやエンジニアなど関係者の方に報告をして、一連のプロセスが完了となります。

お互いにとって相手はどのような存在か

以上のように、Messaging APIの仕様を決めるところから、ドキュメントの公開にいたるまで、エンジニアとテクニカルライターは密接に関わっています。次に、それぞれの立場から、相手はどのような存在か? ということについてお話しします。

エンジニアにとってのテクニカルライターとは(奥薗)

テクニカルライターは、外部の開発者向けにAPIを開発するエンジニアにとって、重要なパートナーだといえます。テクニカルライターの専門知識や視点は、ユーザーに価値を提供するためには欠かせません。

Messaging APIの利用者である開発者の方々は、ドキュメントを通して使い方を学びます。つまり、ドキュメントがわかりにくいと、機能そのものが利用されない可能性があります。このため、機能開発の初期段階から、ドキュメント作成について検討することが重要になってきます。テクニカルライターは仕様策定の段階からプロジェクトに参加するため、エンジニアは読者の視点をふまえた開発が可能になっています。

また、Messaging APIのフィールド名やデータ構造について、テクニカルライターと議論することもよくあります。最近では、テクニカルライターの提案が、データベースのテーブル設計の改善につながったケースもありました。

さらに、テクニカルライターは、新しく開発された機能の初期のユーザーでもあります。QAのプロセスとは別に、テクニカルライターがバグやわかりにくい点を見つけることがあります。実装が完了している場合でも、利用者の視点によるフィードバックを提供し、機能のアップデートや仕様変更を提案することもあります。このようにして、ドキュメントだけでなく、機能自体をさらに使いやすくする役割を担うこともあります。

テクニカルライターにとってのエンジニアとは(銭神)

連携のプロセスでもお話ししましたが、機能の仕様を決めるところから、ドキュメントを書いて公開するまで、私たちテクニカルライターはエンジニアと頻繁にコミュニケーションをとっています。機能の検証をしたり、仕様について確認するときに、ときには初歩的なこともエンジニアに質問をすることがありますが、親切に回答してもらえます。

LINE Developersサイトを見てもわかるように、Messaging APIのドキュメントやリファレンスはたくさんの量がありますが、最近ではエンジニア内でのドキュメントの読み合わせがあり、そこで数多くのフィードバックを受け取りました。「テクニカルライターがいるから、エンジニアはドキュメントと関わらない」という印象がもしかしたらあるかもしれませんが、そのようなことは決してなく、開発者の方にとってわかりやすいドキュメントになるよう、大きな協力を得ています。

また、これはテクニカルライターというよりはいちLINEユーザーとしてですが、たくさんのユーザーに利用されているLINEのAPIについて、その開発に携わっているエンジニアの方とドキュメント作成に携われることを、純粋に楽しく思っています。

このように、テクニカルライターとエンジニアは、別のチームではありますが、同じチームであるかのように連携しながらドキュメントを書くことができています。このようなメンバー同士の近さが、私たちの組織の魅力のひとつだと感じています。

おわりに

以上のように、私たちの組織は、エンジニアとテクニカルライターがお互いに得意なことに集中し、開発者の方により価値を届けられるような体制になっています。最後までお読みいただき、ありがとうございました。