外部APIを公開・メンテナンスしていくうえで欠かせないAPIドキュメントの運用ですが、どのような情報をどのように記載し、Developerにどう届けていくかは難しい課題です。

今回はAPI総研運営の小手川の前職でもあるLINEヤフー社にて、APIリファレンスを含めたDeveloper Productのテクニカルライティングを担当されている銭神さんに、Developerへの情報発信についてお話をお聞きしました。

テクニカルライティングチームの構成について

ECU株式会社 小手川「本日はお時間を頂きありがとうございます。まずは、銭神さんの部署やお仕事のご紹介をお願いしてもよろしいでしょうか。」

LINEヤフー株式会社 銭神裕宜さん（以下「LY銭神さん」）「 LINEヤフーのテクニカルライティングチームにて、LINE Developersサイトのライティングを行っている銭神と申します。

普段はライティングに加え、社内にわかりやすいドキュメントの書き方を広めるためにメンバーからの相談を受けたり新卒向けに講座を開いたりもしています。」

インタビュイー: LINEヤフー株式会社 銭神裕宜さん

社内向けにアドバイスや発信もされているんですね。改めて、テクニカルライティングチームとはどのようなチームなのでしょうか？

LY銭神さん 「現在は6人のメンバーで構成されており、うち1人がエンジニアとしてLINE Developersサイトの開発、他の5人のライターがLINE Developersサイト内のMessaging APIやLINEミニアプリなど複数のプロダクトについてのドキュメントやリファレンスを全員で分担してライティングしています。」

技術的にディープな内容も多いかと思うのですが、エンジニアリングの経験がある方も多いのでしょうか？

LY銭神さん 「メンバーの5人のうち、私を含め4人はエンジニア経験があります。エンジニア出身ではないメンバーについてもGitの使い方やコマンドラインの使い方などの知識を持ったうえで、自分たちでも実際にAPIを叩きながらライティングしています。」

テクニカルライティングチームの普段の業務の流れ

実際にAPIを叩きながらライティングされているのはとても良いですね。私自身、元々LINEにいながらAPIドキュメントが作られる流れを全然把握できていなかったのですが、普段の業務はどのような流れで実施されているんでしょうか？

LY銭神さん 「まず新機能や仕様変更がある場合は開発者やPMから連絡が入り、情報量の多さや変更内容によっては開発者やPMからキックオフミーティングで詳細に仕様のインプットをしてもらうこともあります。社内向けのドキュメントの仕様を確認したうえで、一度実際に手元でAPIを叩いてみて確認するようにします。その際に社内ドキュメントにあった情報と実際の仕様に差異があった場合は開発者に連携し、必要であれば修正していただいています。その後、実際にドキュメントやAPIリファレンスを書いていくという流れになります。」

ライティングのプロセスが品質担保にも繋がっているのは素晴らしい連携ですね。ちなみに開発者からの連携を起点にライティングが始まるとのことだったのですが、テクニカルライティングチームに連絡なく勝手に仕様が変わってしまっていたということは起きたりしないんでしょうか？

LY銭神さん 「4年近くこの会社でテクニカルライティングをしていますが、そのような事例はあまりない印象があります。LINEでAPI開発をしているPMやエンジニアは、Developerにどう告知するかやドキュメントにどのように反映するかを強く意識しながら開発を進めて頂いています。」

Developerへのコミュニケーションやドキュメントの整備がチームをまたいで重要性が認識されているのはとても良いことですね。

LY銭神さん 「最近だと、特に大手企業に影響の大きいAPIレート制限の変更があったのですが、そのような変更だとビジネスサイドのチームでコミュニケーション方針を検討したうえでテクニカルライティングのチームと連携して事前告知を出していくというフローもあります。」

API仕様が変わったときの「事前告知」について

インタビュアー: ECU株式会社 小手川

Developerやクライアントへの仕様変更についての『事前告知』はAPIを運営していくうえでとても大きなテーマだと思っています。事前告知をするうえで、『どんな変更はどんなタイミングでやろう』というような基準もあるのでしょうか？

LY銭神さん 「明確な基準があるわけではありませんが、たとえば破壊的変更については1ヶ月前、影響範囲によっては半年〜1年前など状況によって告知期間を検討しています。最近だとどのような基準で事前告知・通知をするかの定義がDeveloperにとってわかりにくいという課題から、Messaging API開発ガイドラインに事前告知を行わない『非破壊的変更』の定義を明記しました。例えば、『APIレスポンスにフィールドを追加する』といった変更は非破壊的変更としています。」

『非破壊的変更』を明示的に定義するというのは非常に面白いお話ですね。確かに事前告知を受け取れる基準がわかるという意味ではDeveloperからすると助かるなと感じました。

ちなみに私自身もAPIドキュメントを運営していた時期があるのですが、どれだけ丁寧に数多く事前告知をしてもDeveloperに伝わっていないことが多く、苦労した記憶があります。貴社で多くの方に事前告知を届けるための工夫はありますか？」

LY銭神さん 「LINE Developersサイトのニュースに掲載する以外にも、『LINEヤフー Tech』のXアカウントや『LINE Developers』のLINE公式アカウントといったSNSでの告知も実施しています。また『LINE Developersコンソール』というLINEプラットフォームのDeveloperが利用するポータルがあるのですが、そのコンソールにアカウントを登録しているDeveloperの方にはコンソール上の通知アイコンで通知が確認できたりメールで変更通知を受け取れるようにしています。またメール通知は基本的に英語のみですが、それ以外の通知を日本語と英語の両方で実施することで、より広く周知するようにしています。」

確実にDeveloperに情報が届くように多重にお知らせしているんですね。特にLINEヤフーのXはリーチが大きそうですよね。

LY銭神さん 「拡散のしやすさはあると思います。最近だとMessaging APIのMCPサーバーであるLINE Bot MCP ServerをGitHubで公開したというポストがとても話題になりました。このような話題性のある内容は特にスピード感も大事にしており、GitHub公開の当日中にはドラフトを作り、1、2日後にはニュースとして発信していました。私たちのチームでは『役に立つドキュメントで開発をもっと楽しく』というミッションを掲げているので、Developerにとってワクワクするような内容は積極的にスピーディーに発信していきたいなと思っています。」

テクニカルライティングで大事にしていること

より実務的な部分で、具体的にDeveloperに向けたライティングについても深堀りさせてください。Developerに対してライティングするうえで、気をつけていることや意識していることはありますか？

LY銭神さん 「一言でいうと、『読者の悩みを解決すること』をベースに書いています。まずは『読者が誰か』をはっきりさせたうえで、読者が知りたいことや悩みを解決するのが重要だと考えています。読者がDeveloperの場合もあれば企画担当の方の場合もあるので、まずは読者を明確に想定したうえで、考えられる『悩み』を列挙してその悩みを解決してあげることを意識しています。

特に開発ドキュメントについては、読者層が文章を読みたいわけではなく『悩みを早く解決したい』という思いを持っているケースが多いので、早く結論を提示してあげるという部分も意識しています。」

確かにLINE Developersサイトはとても簡潔で、銭神さんの仰るように結論にすぐに辿り着ける構成になっているように思えます。

ちなみに仕様をしっかり明記したとしても読者に届かないというシーンもあるのでしょうか？

LY銭神さん 「確かに実際には記載している情報でもフィードバックフォームでは『記載がないので書いてほしい』と要望が来ることもあるので、コンテンツの検索性については課題感を持っています。」

LINEほどの規模になると、伝えなければならない情報量が多いため情報を届ける難易度も非常に高そうです。

APIリファレンスにはどんな情報を書くか

LINE Messaging APIのAPIリファレンス

例えばLINEのMessaging APIだと、各Endpointのリクエスト・レスポンス情報が記載されたAPIリファレンスとAPIの仕組みや概要、クイックスタートなどが記載されたドキュメントがあると思います。API運営者のよくある悩みだと思うのですが、APIリファレンスにはどんな情報を書くかなどのルールはあるのでしょうか？

LY銭神さん 「リファレンスについては、とにかくコンパクトに仕様だけを記載するようにして、読み物として読んでもらうものは別途ドキュメントとして記載するようにしています。リファレンスに補足的な内容を沢山書いてしまうと情報量が増えてしまうので、今でも『これはドキュメントに移すべきなのでは』といった議論が出ることもあります。」

確かにLINE Developersサイトはリファレンスの情報がしっかり絞られている印象です。ちなみにAPIリファレンスについて今でも課題を感じている部分はありますか？

LY銭神さん 「サンプルコードの部分ですね。現在ではcurlベースのサンプルコードしかないのですが、LINEが提供している各言語ごとのSDKをベースにしたサンプルコードも作っていけると良いなと思っています。」

Endpointごとに複数言語のサンプルコードを書いていくのはとても大変そうですが、どうやって準備していくかの見立てはあるのでしょうか？

LY銭神さん 「SDKがOpenAPI Generatorを拡張したライブラリで作られているので、サンプルコードもOpenAPI Generatorをベースに生成しようとしたのですが、手直しが必要な箇所が多く、結局は手書きでひとつひとつ書いていくのが良いのではという議論をチームではしていますね。」

膨大な量になってしまいそうですが、確かにそれが実現できたらDeveloperからするととても嬉しいですね。他にも課題はありますか？

LY銭神さん 「2年ほど前の話ですが、エラーレスポンスの定義についても課題が大きかった部分でした。元々Endpoint横断で共通のエラー仕様は明記されていたのですが、Endpointごとのエラー定義などがAPIリファレンスに記載されていない状況でした。それだとわかりにくいので、1つ1つのEndpointにエラーレスポンスを追記していきました。」

なるほど。それも価値が大きい一方で、洗い出しの時点でかなり大変そうですが、どうやって進めたのでしょうか？

LY銭神さん 「APIリファレンスを良くしていきたいというモチベーションが高い開発者が社内におり、その方とライターが協業して課題の洗い出しや追記・修正を行いました。」

凄いですね。エンジニアの方の『質の高いドキュメントを提供しよう』という強い意欲が伝わります。

LY銭神さん 「そうですね。昨年、Messaging APIチームの開発者が集まってドキュメントやAPIリファレンスを全て読み込んだうえで、改善点を議論する会も開催され、多くの改善点を洗い出してもらいました。」

テクニカルライティングチームの動き方

ドキュメントを改善していくうえで、開発チームと深く連携しながら動いているんですね。他にもよく関わるチームはありますか？

LY銭神さん 「テクニカルサポートチームは隣のチームなので、問い合わせ内容の共有などコミュニケーションを取ることが多いです。」

確かに質問が良く来る内容からもドキュメントに反映すべきコンテンツも見えてきそうですね。仕様変更や機能リリース、問い合わせなどドキュメントに反映すべきことは多岐にわたりそうですが、チームとしてはどのような優先順位でライティングを進めているのでしょうか？

LY銭神さん 「先ほどお話しした仕様変更などの事前告知や新機能の告知が最優先で取り組んでいる内容です。それ以外は問い合わせやユーザーフィードバックを起点にドキュメントをアップデートしたり、チーム内から挙がった改善点に取り組んだりすることが多いです。」

チーム内でも積極的に改善点を見つけてや施策を打ち出している印象ですが、チームとしてKPIのようなものがあるのでしょうか？

LY銭神さん 「フィードバックフォームの評価は定期的にチェックするようにしていますが、具体的なKPIはありません。どちらかというと、『こういったものがあったらわかりやすいよね』とどんどん書いていくイメージです。例えば複数あるDeveloper向けプロダクト横断で存在するチャネルアクセストークンのような概念を横断的に解説するページのようなものは直接的に要望はないものの、あったほうが利用者の理解の助けになると思い制作しました。」

先ほどの『役に立つドキュメントで開発をもっと楽しく』というミッションのもとMCP Server公開をスピーディーに発信されたお話につながる部分がありますね。ミッションと主体性を重視する点にLINEらしさを感じました。

銭神さんが思う良いAPIドキュメント

余談に近いですが、ここまで充実したAPIドキュメントを書かれている銭神さんから見て、良いなと思うAPIドキュメントってありますか？」

LY銭神さん 「やはりStripeはすごいなと思いますね。特にリファレンスの中にPlaygroundがあってAPIを試せるのが良いなと思います。あとはAPIというよりはドキュメントとして、SmartHRのユーザーマニュアルはとても見やすくてわかりやすいなと思っています。」

まとめ

今回のインタビューを通じて、Developerに早く正しく情報を届けるうえでの銭神さんをはじめとしたテクニカルライターの方々や、API開発者のみなさんの強いこだわりや洗練されたプロセスを改めて知ることができました。

自社に専任のテクニカルライターがおらず、開発者だけでAPIドキュメントを運用している会社も多いかと思いますが、Developerへの情報発信において今後参考にできるポイントがあれば当メディアとして幸いです。