読了時間：9分
API は世界を動かしている。 開発者はほぼ毎日APIを使っています。ある試算によると、彼らはなんと週に10時間以上もAPIを使って作業しているそうです。 これは、それらを使用するだけでなく、調査、サポートのためのグーグル検索、レビューの研究、そしてもちろん、ドキュメントをあさることも含みます。 APIがどれだけ明確で、簡単で、便利で、サポートされているかは、開発者体験（DX）全体、つまり開発者が製品に対して抱く感情的な反応を決定する。 APIエコノミーでは、優れた開発者体験が基本である。 開発者の成功を助け、使う喜びを感じられるAPIは、多くのユーザーを獲得し、競争相手から抜きん出ることができる。
このビデオで API テクノロジーの入門を見る
今日は、API ドキュメントで肯定的な開発者体験をどのように育成するかについてお話します。 しかし、まず、何が悪い API ドキュメントを作るのかを理解する必要があります。
What Developers Hate in API Documentation
開発者コミュニティは情熱的なものです。 特に、彼らが好まないものに対して情熱的です。 彼らが API を好まない場合、製品が実際に素晴らしいものであっても、ほとんどの場合、ジャンクなドキュメントが原因です。 以下は、開発者が API ドキュメントに対して持っている一般的な問題です。 これは、自動生成されたドキュメントや作成者が放置しているドキュメントによくある問題です。 多くのドキュメント生成ツールはコードにコメントすることでは素晴らしい仕事をしていますが、開発者やテクニカルライターが書いた英語での実際の説明にはかないません。
コードサンプルが非常に少ない。 これも、説明は豊富だが、実際のコードの例がほとんどないことの端的な例です。 このあまり巧みでないやり方は、マーケティングには何の役にも立ちません。 (まともな人ならそうするように) あなたの API が何をするのか知りたい人をイライラさせるだけです。
長すぎる/見つからない/不正確/何年も更新されていない、など。 良いドキュメントを作成することは、良い API を構築することとほぼ同じくらい重要です。 なぜなら、お粗末なドキュメントや、「製品API」でググっても見つからないようなドキュメントは、開発努力全体を失敗させるからです。 もし興味があれば、我々はすでに一般的な技術文書に関する仕様を概説している。 しかし、APIドキュメントは専用の記事を書く価値がある。
Adopt spec-driven development
Spec-driven development (SDD) はテスト駆動開発に似ており、各機能のテストケースを書き、それをパスするようなコードを記述するものです。 SDD では、API の構築と並行してドキュメントまたは少なくともその一部を作成し、多くの場合、仕様と呼ばれる特定の API 記述形式に従っています。
API 仕様は将来のドキュメントのテンプレートのようなもので、あなたの API の設計を記述する統一言語、それがどう機能し、そこから何を期待するかを説明するものです。 RAML (RESTful API Modeling Language)、OpenAPI (旧 Swagger)、および API Blueprint など、いくつかの仕様がありますが、OpenAPI のフードの下にすべての仕様を組み合わせる傾向があります。 たとえば、API Console は RAML および OpenAPI フォーマットからドキュメントを自動的に生成し、既存の Web アプリケーション上またはスタンドアロン アプリとして実行できます。
API Console では RAML および OpenAPI 仕様から API ドキュメントの Web ポータルを構築できます
Source: Pawel Psztyc
WordPress や Drupal CMS のような従来の API ドキュメント ソリューションの代わりに、API 仕様製品はオープン ソースであり、開発コミュニティによって開発コミュニティのために作られ、異なるプログラミング言語のパーサーがあり、常に作成者のサポートがあります。 しかし、テクニカルライターでさえ、専門用語がテキストに少し漏れる傾向があります。
API は他のソフトウェア製品と同様に、特定の読者のために作成されます。 しかし、ドキュメントの読者は広大である。
- ドキュメントと密接にやり取りする開発者
- CTOやソリューション設計者のような意思決定者で、あなたのAPIが良いフィットであるかを迅速に判断したい
- ジャーナリスト、技術ライター、そして必ずしもあなたの API をこれまで使用しない競合他社のようなオブザーバー。
そして、これらの各グループ内にも、異なるスキル、役割、およびニーズを持つ人々がおり、彼ら全員がドキュメントで肯定的な経験をする必要があります。 全員を対象にするにはどうしたらよいでしょうか。 最も経験の浅いユーザーをターゲットにすることです。
技術的なことよりも機会から始める。
Amazon Alexa API ドキュメントは、Alexa が何を行い、クライアントにどんな利益をもたらすことができるかを説明することから始まります。 API ドキュメントは、ユーザーが API について膨大な経験を持っていることを前提とし、圧倒されすぎることで悪名高いものです。
Facebook は初心者のために明確な参照を提供し、段階的に開始するプロセスを追います
最もよくある使用例に対する指示を作成する。 おそらく、人々がどのような機能のためにAPIを使用するか、すでにご存知でしょう。 それらに対応する別のセクションを作成し、そこにサンプルメッセージを含めます。
会話調を使用する。 開発者コミュニティはのんびりしていてカジュアルなので、たとえそれが「プロフェッショナル」に聞こえたとしても、ドライな会社言葉は喜ばないでしょう。 良いドキュメントは常に人間に語りかけるものである。 もしあなたのAPIがOAuthやnpmのようなサードパーティ製品やコンセプトの使用や理解を必要とするなら、ドキュメントやインストールガイドへのリンクを含めることだ。 API ドキュメントは IKEA の組み立て説明書ではなく、学習ソースである。 FAQ、チュートリアル、ブログ、そして可能な場合は動画でも、ドキュメントを充実させましょう。
必携のセクションを組み込む
2019年に、Swaggerの開発元であるSmartBearが、API開発者とユーザーを調査しました。 彼らは、コミュニティで最も重要だと考えられている docs 機能を見つけ、開発者がカバーしたい必携のドキュメント セクションのリストを提供しました。 そのうちのいくつかを見ていきます。
SmartBear は 3,000 人の API 実務者を調査し、
Examples. 例は通常、コードの断片として提示され、それは十分に有用ですが、さらに実用的なものにすることができます。 例えば、Medium のドキュメントで行われているようなフィールドのトランスクリプトを含めたり、開発者が実際に呼び出してテストして使えるようなモック API を作成したりすることもできる。 モック API は、URL や GitHub で簡単に共有でき、ある程度のレベルに達していれば、最終製品で使用することもできます。
Status and errors. 標準的なステータスコードと、APIのものに固有のものがあります。 それはあなたのAPIによって引き起こされることができるすべてのエラーを含めることをお勧めします。 エラーはしばしばドキュメントの専用ページに置かれますが、最も多く表面化するエンドポイントの直下にそれらのいくつかを複製することは理にかなっています。 ほとんどの API ドキュメントは、認証と承認から始まります。 API キーの取得方法や、起こりうるエラー、トークンの有効期限、認証感度に関する説明 (基本的にキーは共有できないこと、そしてどこで使用できるかを思い出させる) など、リクエストを認証する方法に関する情報をカバーする必要があります。 HTTP で Web リクエストを提供することは、ドキュメントとして最低限必要なことです。 通常、開発者は選択した言語で HTTP リクエストを送信する方法を知っていると想定されますが、API 制作者はさまざまな言語でのリクエストを含むことがあります。 これは、API 仕様ツールや Postman のような API 管理ツールによって自動的に行うことができます。
業界標準のレイアウトを使用する
ドキュメント生成ツールを使用している場合、レイアウトはすでに決定されています。 ほとんどの API ドキュメントは同じように見え、同じように感じられます。 もしあなたがいくつかのものを使用したことがあるなら、新しいドキュメントにどのようにアプローチすればよいかを知っているはずです。 それでも、大量のデータを整理し、見つけやすく、ナビゲートしやすくするのは、複雑な作業です。 ここでは、最も機能的なレイアウトの特徴をいくつか紹介します。
Dynamic layout (動的レイアウト)。 静的なドキュメントによって、時代遅れの API を見分けることができます。 1 ページまたは PDF ドキュメントでさえも、2020 年にはそれをカットしません。 動的なドキュメントは、目を通し、更新し、ブックマークするのが簡単です。
Sticky contents. いいえ、ナビゲーションバーは気を散らすこともなく、貴重なスクリーンスペースを奪うこともありません。
3カラムレイアウト：常にコンテンツが目に入るようにします。 あまり使用されませんが、このレイアウトでは、コード例用に右側にもう 1 つの列を持つことができます。 もちろん、これは、大量のテキストがあり、ユーザーが前後にスクロールしたり、タブを切り替えたりする必要がないように、コードを強調したい場合にのみ意味を持ちます。
HubSpot API ドキュメントは 3 列レイアウトを使用する
Use contrast colors for syntax. 開発者はコード例を見るのにかなりの時間を費やすので、読みやすくし、異なるコンポーネントを色で区切ります。
この Facebook のグラフ API ドキュメントの例では、SDK 間の選択に異なるタブを使用する方法も示しています
Saved scroll state (スクロール状態の保存). これは、開発者なら誰でも感謝する小さなディテールです。 また、アンカー リンクを使用して、ユーザーが URL をコピーした場合にページの異なるセクションを指定することもできます。 もし人々がドキュメントを気に入れば、彼らは競合他社よりもあなたの API を使用し、その周りのコミュニティを推進するでしょう。 通常の「このページは役に立ちましたか？」メッセージは、開発者の質問にどれだけうまく対処しているかを知らせ、フィードバックフォームは、あなたがそれを提供する限り、頻繁に使用されるでしょう。 これはまた、最も一般的な間違いの 1 つでもあります。 開発者はしばしば、更新をロールアウトした数日後に更新について書き、時には数文に制限されます。 これは、ドキュメントの更新について確立されたプロセスがなく、誰の責任でもないために起こる。 ここでは、定期的で有用なドキュメントの更新を確実にする方法を説明します。
更新前にドキュメントを準備する。 更新を紹介するための、よく書かれ、詳細で、編集されたパラグラフを用意する前に、それをロールアウトしないようにしましょう。
非推奨のデータを定期的に削除する。 ドキュメントは頻繁に、少なくとも数カ月に一度は見直されなければなりません。 ユーザーフィードバック機能により、矛盾を早期に発見することができ、それらをレビューし、更新に対応する責任者が常にいる必要があります。 標準的な API 分析は、どのエンドポイントがより頻繁に使用されているかを教えてくれるので、ドキュメントの特定の部分に焦点を当て、より有用な情報を提供したり、専用のチュートリアルを作成したりすることができる。 あなたの API が使用されるユースケースを監視することで、価値提案を広げ、より多くの可能性を持つドキュメントを更新することができます。
素晴らしい API ドキュメントの例
探索し、そこから学ぶべき優れたドキュメントが大量にあります。 この記事で共有した例に加えて、さらにいくつかの例を紹介します。
Medium API ドキュメント
Medium API ドキュメントは、今日挙げたすべてのルールに必ずしも従っているわけではありませんが、この API がサポートする限定機能 (Medium 上の出版物の投稿と検索) にとって素晴らしいものとなっています。 GitHub で共有されており、本当に短くて明確な内容で、たくさんの例があり、それぞれのコードで言及されているすべてのパラメータの記録で終わり、起こりうるエラーも含まれています。
Mailchimp API documentation
Mailchimp はその利用者のほとんどがマーケティングのプロであることを認識しており、非技術者でもその API をどう扱うかを理解できるような言語を使用しています。
- エンドポイントが何をするのか、このガイドで何ができるのか
- 何が必要か – ユーザーが最初に取得しなければならないアクセスやアカウント
- 各機能はテキストの説明、複数の言語でのコード例、時にはインターフェースのスクリーンショットで構成されていることです。
Twilio API documentation
Twilio の API ドキュメントは非常に優れていることはよく知られています。 ドキュメントはTwilioが共有するすべてのヘルプの氷山の一角に過ぎませんが、いくつかの言語でのSDKとiOS、Android、Web用のサンプルアプリがあります。 まず、ガイドの右側に直接コードが記載された3列のロジックに従っています。 簡単な動作は詳細に説明され、追加情報やスクリーンショットのリンクも多数用意されています。 フィードバックは、[このページを評価する] ボタンとサポート チームへのリンク、および StackOverflow のタグによって促進されます。 基本的な機能のデモ、モック アプリ、Spotify API とウィジェットを使用して構築されたライブ サンプル、さまざまなプログラミング言語用のラッパー、そしてもちろん、コンソールがあります。 コンソールは基本的にインタラクティブなドキュメントで、あなたの（またはサンプルの）データを入力し、エンドポイントをライブで探索することができます。 強力な製品と強力な知識ベースにより、Spotify は開発者が一緒に仕事をしたいと思う信頼できるパートナーとなっています。
Treat docs with care
ドキュメントはほとんどのユーザーとの唯一の接点なので、ドキュメントを通して明確にコミュニケーションすることを学ぶ必要がある。 ここでの最良のヒントは、それを誰かの仕事にすることです。 多くの場合、様々なスキルを持つ読者への話し方を熟知し、開発者の言葉を実用的なポイントに翻訳し、ドキュメントのタイムリーな保守と更新を監視するテクニカルライターが担当します。 しかし、優れたドキュメントを管理することは、専門家がいなくても可能です。 Swagger UI、Spotlight、Apiary、docs仕様作成ツールなどのAPI管理ツールは、開発者が喜ぶドキュメントを作るための幅広い機能を備えています
。