LINE Engineering
Blog

API the Docs参加レポート

Serizawa 2018.05.17

LINEプラットフォームの開発者向けドキュメントを担当しているテクニカルライターです。

はじめに

こんにちは。テクニカルライターのSerizawaです。LINEには、エンジニアが最新の技術動向を把握できるよう、海外で開催されるカンファレンスに会社負担で参加できる制度があります。今回の記事では、その制度を利用して参加してきたAPIドキュメンテーションのカンファレンス「API the Docs」の様子をご報告します。

API the Docsは、テクニカルライター、API開発者、プロダクトオーナー、エバンジェリスト向けに年に数回世界各地で開催されている、APIドキュメンテーションに特化したイベントです。デベロッパーエクスペリエンスの重要な要素であるドキュメンテーションについて、最新のベストプラクティスやトレンドについて知見を共有し、意見を交換する場になっています。

今回のAPI the Docsは、今年4月24日、パリ市内の中心部にあるMozillaオフィスで開催されました。APIエキスパート、コンテンツストラテジスト、ソフトウェア開発者など、異なる立場からAPIドキュメントや開発者ポータルの開発・運営に携わる方々により、10件の講演が行われました。講演内容は、「開発者向けポータルが備えるべき要素は何か」という全般的な議論から、OpenAPIを使ってドキュメントを生成するテクニックや、ポータルのプラットフォーム移行をめぐる苦労話のような具体的な情報共有まで、多岐にわたります。本記事では、LINEプラットフォームのAPIドキュメンテーションを担当するテクニカルライターとして、特に興味深かった講演について紹介します。

なお、各講演の概要や資料はPronovixのブログ記事「API the Docs Paris 2018」から参照できます。オープンAPIに関連する業務をしている人なら何かしら興味を惹かれるトピックがあると思いますので、ぜひご覧になってみてください。

PSD2を背景とするバンキングAPIポータルの現状

この講演は、API AcademyのリードAPIエコノミストであるMehdi Medjaouiさんにより行われました。

PSD2(新EU決済サービス指令)は2016年1月に施行されたEUが定める決済サービス指令です。この指令は顧客が合意した場合、金融機関がサードパーティに顧客の口座情報を提供することを求めているため、フィンテックサービスが活性化し、顧客の利便性が高まることが期待されています。PSD2に準拠する金融機関では開発者ポータルを開設して、口座情報の取得や振り込み指示を実行できるオープンAPIを公開しているのですが、Medjaouiさんはそのうち8つの銀行の開発者ポータルを比較し、先進的な取り組みを見せているポータルにはどのような機能が備わっているかを明らかにしてみせました。

銀行によって開発者ポータルの利便性に大きな違いがあるものの、円滑なユーザー登録のプロセスやAPIの動作を実際に試せるサンドボックスなど、サードパーティの開発者が開発者ポータルに求める要素を完全に満たすサイトは比較対象の中に存在せず、フィンテック業界のトップを行くStripeSquareのレベルに追いつくには改善の余地があることが示されました。国際的な銀行のような大企業でも試行錯誤が続いており、APIの公開、利用促進の手法はまだ確立されていないことがわかりました。

Medjaouiさんのスライドには、開発者が開発者ポータルに求める要素や、使いやすいポータルの実例が列挙されています。日々の業務に追われて思いつかずにいた、実装すると確かに便利な機能などに気づくことができて、大変ためになりました。

DXの立案・設計―開発者ポータルが備えるべきドキュメントとは

この講演は、PronovixのテクニカルライターであるKathleen De Rooさんにより行われました。

DX(デベロッパーエクスペリエンス)を設計するとはどういうことでしょうか。開発者ポータルの場合は、開発者が開発サイクルの各段階で直面する問題に自ら対処できるように、多様なドキュメントの提供方法を設計することです。この講演では、それぞれの段階で開発者に必要なドキュメントのカテゴリや、目的や対象読者が異なるさまざまなドキュメントにアクセスしやすいトップページのデザイン、開発者ポータルの信頼性を高めるために備えるべき項目など、具体的なベストプラクティスが挙げられました。

外部開発者がオープンAPIを利用するプロダクトを開発して運用段階に至るまで、開発者ポータルはセルフサービスのサポートハブの役割を担います(良くできたポータルがあればサポートコール数は少なくなります。例えば前述のStripeでは、サポートに問い合わせる顧客は全体の10%未満だそうです)。優れたDXを提供するには、試用から運用まで、開発者がたどる段階を適切にサポートするさまざまなカテゴリのドキュメントを準備する必要があります。たとえば、まずはAPIを試してみたい開発者にとっては、APIの概要を簡単に把握し、動作を確認できるページが必要ですし、実際にAPIを利用したい開発者にとっては、利用プランや価格体系の情報が必要です。また、実装段階の開発者には、陥りやすい問題を解説するFAQページや、他の開発者と意見を交換できるフォーラムが役立つでしょう。

特に印象に残ったのは、開発者ポータルで何を達成したいのかを考えるとき、「外部開発者にAPIのファンになってもらうこと」も目標に含めるべきという観点です。開発者ポータルの運営には、API自体の資料を完備するだけではなく、コミュニティの活性化やブログによる情報発信を受け持つデベロッパーリレーションズチームとの連携が欠かせないといえるでしょう。

ドキュメンテーションにとどまらないOpenAPI活用方法

この講演は、StoplightのリードコミュニティエンジニアであるTaylor Barnettさんにより行われました。

OpenAPI(旧Swagger)仕様は、REST APIを記述するためのオープンな規格です。この講演では、API設計の支援、モックアップの作成、APIが仕様どおりに実装されているかの確認など、さまざまな用途でOpenAPI仕様を活用できることが紹介されました。

OpenAPIでは構造化されたアプローチをとるため、ドキュメンテーションツールとして利用すると、ゼロから書き出すのに比べて簡単かつ短期間に、統一した用語を使ってドキュメントを作成できます。しかしそれに加えて、API開発者のDXを高めるためにOpenAPIを活用できることは、まだあまり注目されていないようです。Barnettさんはその点に注目し、エンジニアの視点で、APIの設計、モックアップ、テスト、フィードバックの4つの領域で、OpenAPIを業務に取り入れる利点を解説しました。

どの領域にも共通する利点は、「実装を待たずにチェックする」「自動化により漏れをなくす」「共通のフォーマットで協働を促進する」ことです。実装とドキュメントのギャップをチェックするフレームワークであるDreddやリンターのspeccyなども公開されてきています。本講演の原題は「Going to Infinity and Beyond Documentation with OpenAPI(OpenAPIを使ったドキュメンテーションを超えて無限の彼方へ)」というものでしたが、その名のとおり、OpenAPIベースのAPI開発には大きな可能性が広がっていそうです。

おわりに

今回初めて海外のカンファレンスに参加して、APIドキュメンテーションの領域で求められる専門性の多様さに圧倒されました。読み手に伝わるコンテンツの作成は、テクニカルコミュニケーションのごく一部の要素です。利用しやすく信頼できる開発者ポータルを維持し、その技術基盤を効率よく改善し続けるには、さまざまな技術分野に強みを持つメンバーがチームになって取り組む必要があると強く感じました。

それと同時に、現在のLINE Developersサイトをより良いものにするための具体的なヒントも多く得られました。できることからひとつずつ、サイトを改善していきたいと思います。

さて、LINEでは、英語および日本語のテクニカルライターを募集中です。わたしたちと一緒にテクニカルドキュメンテーションの可能性を追求したい!という方は、ぜひ以下のフォームからご応募ください。

皆さんのご応募を、心よりお待ちしています。

Technical writing

Serizawa 2018.05.17

LINEプラットフォームの開発者向けドキュメントを担当しているテクニカルライターです。

Add this entry to Hatena bookmark

リストへ戻る