APIの状況は急速に拡大しています。組織はこれまで以上に接続されたウェブサービスと統合に依存しており、プロバイダーはAPIの採用を劇的に増やす機会を得ています。
開発者は、習得しやすく、期待どおりに動作するAPIを使いたいと考えています。高品質のドキュメントは、期待を設定し、ユーザーを教育し、開発者がサービスで新しいプロジェクトを開始するように促すことができます。
ここでは、あなたのチームがクラス最高のドキュメントを設計するためのいくつかの方法を紹介します。
1. 大きなストーリーを語る
誰かが初めてあなたのAPIドキュメントを見に来たとき、彼らは何に迎えられますか？
採用を促進し、常連ユーザーの基盤を構築しようとしている場合は、ストーリーを語る必要があります。ドキュメントは通常技術的で網羅的であるため、評判が悪いことがありますが、多くの企業にとって、ドキュメントは製品のパッケージングと取扱説明書の両方になっています。
あなたのストーリーは何ですか、そしてあなたのAPIの消費者はそのストーリーでどのような役割を果たしますか？たとえば、Marvelは開発者がコミックの正典を照会できる公開APIを持っています。
Marvel APIドキュメント：https://developer.marvel.com/docs
誰かがポータルに到着すると、「世界最高のコミックAPIで素晴らしいものを作ろう」というストーリーがはっきりとわかります。
あなたの組織のAPIは超能力に頼っていないかもしれませんが、あなたの強みを語り、開発者をあなたのAPIとの連携に興奮させるようなストーリーがきっとあるはずです。
2. 明確な開始点を提供する
さて、魅力的なストーリーで新しいユーザーを盛り上げました。次は何でしょうか？
開発者が最初にどこに行けばAPIに慣れることができるかをわかるように、明確な開始点を提供します。人気のメッセージングツールであるSlackのAPIドキュメントは、これをうまく行っています。彼らは「Build: brilliant bots」というダイナミックな見出しでストーリーを語り、「Start here」セクションでサイドパネルナビゲーションを紹介しています。
Slack APIドキュメント： https://api.slack.com/
誰かがスクロールダウンする前に、APIについて学び始める明確な場所があり、Slackが新しいユーザーに期待を設定するための専用の場所も提供しています。「Start here」セクションは、計画から設計、構築へと進む標準的なソフトウェア開発ライフサイクルと一致しています。あなたのAPIにとって最も理にかなった構造を検討してください。しかし、新しいユーザーが初めてドキュメントにアクセスしたときに方向性を提供していることを確認してください。
3. 一般的なユースケースを促進する構造を作成する
開発者が純粋に閲覧しているのではない限り、彼らがあなたのドキュメントにたどり着く頃には、おそらくすでにプロジェクトを念頭に置いているでしょう。あなたのAPIがサポートできる最も一般的なユースケースやアクションを明示することで、開発者が必要な情報を見つけるのにかかる時間を短縮できます。Slackもこれをうまく行い、ホームページで「メッセージを送信する」「シンプルなワークフローを作成する」「ボットを構築する」などのアクションを強調しています。
エンドユーザーがどのようなものを作成しようとしているのか、そして最も役立つ情報を事前に提供する方法について時間をかけて検討してください。APIを使った最初のプロジェクトを簡単にできれば、彼らが定期的に戻ってくる可能性が高まります。
4. まずは人間向けに書く
一部の開発者は、ドキュメント以外であなたの組織とやり取りすることはないかもしれません。ドキュメントがすべて臨床的で乾燥している場合、開発者は必要なものを見つけるかもしれませんが、その体験は際立たないでしょう。ドキュメントのトーンについて考えてみてください。会話的ですか？
開発者があなたの隣に座っていたら、認証オプションをどのように説明しますか？
信頼できる必要があるため、スラングを使いすぎたり、やりすぎたりしないでください。しかし、退屈で謎めいたものにもしないでください。始めるには、既存のドキュメントを可読性計算機で実行してみるとよいでしょう。
これらの計算機は、正直さを保ち、長文や長すぎる単語が多いセクションを強調表示します。コーディングは十分難しいものです。読むことは簡単であるべきです。
5. 包括的にする
開発者は、プロバイダーのAPIドキュメントに多くを期待しています。私たちの2019年のAPIレポートでは、回答者に「APIドキュメントで最も重要だと思う5つのこと」を選択するよう求めました。以下は3,000人以上のソフトウェア専門家からの結果です。
消費者に提供するリソースが網羅的であることを確認してください。あなたのドキュメントにアクセスする可能性のある最も熱心なユーザーを想像し、ドキュメントの不足が彼らを妨げないようにしてください。
それは、ユーザーに可能な限りのすべての情報を洪水のように与えるという意味ではありません。ドキュメントに階層構造を採用し、ライトユーザーが一般的なユースケースにすぐに取り組めるようにし、パワーユーザーが心ゆくまで詳細をクリックできるようにします。
6. インタラクティブにする
上記のグラフで、回答者は「例」をAPIドキュメントの最も重要な要素として選択しました。開発者は、あなたのAPIで何が可能かをできるだけ早く実践的に試してみたいと思っています。
インタラクティブなドキュメントを使用すると、開発者はさまざまなAPI呼び出しをすばやくテストできます。先ほど参照したMarvelポータルにはこのオプションがあります。アカウントを作成すると、APIキーが自動的に提供されます。そのキーを使用して、すべての異なるエンドポイントに対して呼び出しを行い、さまざまな操作をテストできます。このインタラクティブなページは、開発者が予想されるパラメーターとエラーメッセージに慣れるのにも役立ちます。
Marvelのインタラクティブドキュメント： https://developer.marvel.com/docs
7. OpenAPI仕様でAPI設計を標準化する
OpenAPI仕様（以前はSwagger仕様として知られていました）は、REST APIのAPI記述形式であり、急速に業界標準となっています。私たちの2019年のAPI調査では、回答者の約70%がAPIの定義にSwagger/OpenAPI標準を現在使用していることがわかりました。
この形式は、学習しやすく、人間と機械の両方にとって読みやすいように設計されています。
APIを一貫した方法で構造化することで、組織は開発者に一貫した体験を提供できます。彼らは何を期待し、どこで見つけられるかを知るでしょう。
OpenAPI仕様を採用する組織は、SwaggerUIなどのオープンソースツールを活用して、API定義を自動的にインタラクティブなドキュメントに変えることができます。
Swagger Petstoreにアクセスして、SwaggerUIによるドキュメントがどのように機能するかを確認できます：https://petstore.swagger.io/
SwaggerUIと、その他のすべてのオープンソースSwaggerツールは、SwaggerHubと呼ばれる1つの中央プラットフォームで利用できます。チームがOpenAPI仕様を中心に標準化しようとしている場合は、無料アカウントを作成して、すぐにAPIのインポートを開始できます。
8. チュートリアル、FAQ、ケーススタディを強調する
あなたのドキュメントは、APIの学習プラットフォームです。
APIの使い方は説明できますが、APIの**使い方を示す**ことで、本当にAPIを生き生きとさせることができます。簡単なプロジェクトタイプのチュートリアルを作成し、ドキュメント内でそれらにリンクします。以下のSlackの例は、彼らがAPIユーザーを教育するために構築し、宣伝している記事とチュートリアルの種類を示しています。
Slack APIチュートリアル： https://api.slack.com/tutorials
彼らはいくつかのケーススタディもリストアップしています。APIの採用を本当に促進するには、訪問者を教育するだけでなく、新しいプロジェクトのインスピレーションも提供する必要があります。
Slackが引用している創造的な例の1つは、オフィスでの食事の注文を調整するのに役立つペンギンをテーマにしたボットであるKipです。最も創造的なユーザーを強調することで、開発者がAPIで何が可能かを確認しやすくします。
9. ユーザーからのフィードバックを促す
あなたのドキュメントはどのくらい効果的ですか？
ページビュー、消費者、呼び出し数などの異なる指標を代理として見ることができますが、これらの指標だけでは、あなたのチームは多くの仮定をするしかありません。
ユーザーを調査して彼らがどう考えているかを確認することもできますが、プロセスやインフラストラクチャに組み込まれていない場合、ユーザーからのフィードバックを求めることに規律を保つのは難しい場合があります。最高のドキュメントは、ドキュメント内でユーザーからのフィードバックを促します。
人気の決済ベンダーであるStripeは、ドキュメントの各セクションの最後に「このセクションは役に立ちましたか？」と尋ねることでこれをうまく行っています。ユーザーは、閲覧中に「はい」または「いいえ」をクリックするのにほとんど時間をかけません。
この質問をすることで、どのセクションが最も役に立たないと評価され、どのセクションに最も熱心な訪問者がいるかを明確に確認し、それに応じて改善を優先することができます。
Stripe APIドキュメント： https://stripe.com/docs/api
この要素は、既存のドキュメントの定量的な尺度を提供しますが、何が不足しているかはまだわかりません。埋め込み型の定量的尺度を定性的な調査と組み合わせることで、ドキュメントの状態をかなり正確に把握できます。
10. 最新の状態に保つ
物事をより混乱させるだけのドキュメントを読むのは本当にイライラします。
ドキュメントが最新ではない場合、あなたの組織の評判を悪くし、開発者があなたのAPIと関わることを躊躇させる可能性があります。
私たちの2019年のAPIレポートでは、回答者に「最新のAPIドキュメントを提供する上での最大の障害は何ですか？」と尋ねました。上位3つの回答は次のとおりです。
- ワークロードによる時間と/またはリソースの不足
- 納品速度に対する要求の増加
- ツールまたはテクノロジーの不足
これらの課題に対処するには、チームはプロセスを高速化し、時間を節約できるツールに頼る必要があります。SwaggerUIやSwaggerHubプラットフォームのようなツールが、API定義のドキュメントを自動的に生成できることをすでに述べました。
それ以外に、チームの速度を低下させる依存関係を探してください。ドキュメントチームは、作業を開始する前に開発作業が完了するのを待つ必要がありますか？
他のチームの作業を待つと、避けられない時間的な制約が生じ、その結果、ドキュメントの品質が損なわれます。
チームがOpenAPI仕様を使用している場合、ServiceV ProやVirtServerのようなツールを使用すると、API設計を仮想サービスに簡単に変換し、チーム間で共有できます。
ドキュメント、開発、テストの各チームはすべて、仮想サービスを使用して並行して作業できます。プロジェクトの共有された唯一の真実のソースがあれば、他のチームを待つことなく、期待される応答を正確にドキュメント化し始めることができます。
チームがSwaggerHubを使用している場合、仮想化をワークフローの自然な一部にするために、ServiceVとの簡単な統合があります。
APIドキュメントについて詳しく知る
ドキュメントのベストプラクティスについてもっと読みたいですか？これらはこの作品に情報を与えるのに役立った、この主題に関する私たちのお気に入りの記事の一部です。ぜひチェックしてみてください！
もっと読む