Your API Docs Are Why Nobody Uses Your API \u2014 TXT1.ai

誰も話さない230万ドルのドキュメンテーションの問題

私はサラ・チェンで、過去11年間、3つの異なるAPI中心の企業で開発者リレーションのリーダーを務めてきました。2019年、私はあるシリーズBのスタートアップが「物流APIのストライプ」と呼ぶものを構築するために230万ドルのエンジニアリングリソースを燃やしていく様子を見ました。この製品は本当に革新的でした—リアルタイムのパッケージ追跡と1秒未満のレイテンシー、予測配送ウィンドウ、シームレスなキャリア統合を提供していました。ローンチから6か月後、彼らは47件のサインアップを獲得しました。12か月後には、3人の有料顧客しかいませんでした。

API自体は問題ではありませんでした。私自身でテストしましたが、速くて信頼でき、実際の痛点を解決していました。しかし、ドキュメンテーションは開発者を遠ざけるマスタークラスでした。機能しない認証例。APIが何をするかすでに知っていると仮定したエンドポイントの説明。一つの言語（Java、当然のことながら、バックエンドチームが使用していた言語）のコードサンプル。インタラクティブなプレイグラウンドなし。実際のユースケースなし。ただ、自動生成されたリファレンスドキュメントの壁があり、ロボットによって書かれた電話帳のように読まれました。

その会社は結局方向転換しました。しかし、私を悩ませるのは、これは例外ではなかったということです。私のキャリアの中で、89の異なるAPIのドキュメンテーションをレビューしてきました—小さなスタートアップからフォーチュン500企業まで。実際に開発者を成功に導いた数を片手で数えることができます。他は？それがあなたのAPIのアクティベーション率が3%である理由です。それが、開発者がサインアップして20分間イライラし、二度と戻ってこない理由です。

これは「書くのが得意である」ことではありません。あなたのドキュメンテーションが製品の初印象であり、営業チームであり、サポートシステムであることを理解することです。そして今、それはおそらくあなたの価格設定が決して引き起こさない以上に多くの顧客を失わせています。

APIの成功を予測する5分テスト

私が評価するすべてのAPIに対して行うシンプルなテストがあります。「5分間の初回呼び出し」テストと呼んでいます。これがどのように機能するかをご説明します: アカウントを作成し、ドキュメントに移動し、5分以内に初めての成功したAPI呼び出しを行おうとします。製品の事前知識はありません。営業やサポートからの助けもありません。私、ドキュメンテーション、タイマーだけです。

「ドキュメンテーションはオプションではなく、1,000万ドルのARR APIビジネスと200万ドルの廃棄費用の違いです。開発者は心を読むわけではありません。彼らはドキュメントを読みます。」

結果は壊滅的です。過去3年でテストした89のAPIのうち、成功したのはわずか7つ。成功率は8%。最初の成功した呼び出しまでの平均時間は？34分。APIと関わってきたのは2013年以来の私ですが。ジュニア開発者やあなたのドメインに不慣れな人にとっては？その時間を2倍または3倍します。

面白いのは、最良のドキュメンテーションを持つ企業は、必ずしも最大の予算を持つ企業ではないということです。Stripeは素晴らしいドキュメントを持っていますが、Plaidもそうです。Twilioもそうです。Resendもそうで、2年未満で立ち上げた会社です。共通しているのはリソースではなく、哲学です。これらの企業は、ドキュメンテーションが発売後のチェックリスト項目ではなく製品そのものであることを理解しています。

ほとんどのAPIがこのテストに失敗する理由を掘り下げると、3つのパターンが一貫して浮かび上がります。まず、明確な「始め方」パスがありません。開発者がリファレンスページにアクセスし、基本を逆にエンジニアリングしなければなりません。次に、認証が後回しにされています—あいまいな指示、欠落した資格情報、不明瞭なスコープ。三番目は、これは致命的です：即時フィードバックループがありません。開発者は、セットアップに30分以上投資しなければ、正しく行っているかどうかわかりません。

私のテストをクリアする企業は、全く異なるアプローチを取ります。彼らは、あなたが何も知らないことを前提としています。最初の60秒で動作する例を提供します。リクエストを発行する前にレスポンスを示します。彼らは成功を必然的なものに感じさせます。パズルを解くようなものではありません。

自動生成されたドキュメントが採用を阻害する理由

率直に申し上げますが、あなたのドキュメンテーションが主にコードコメントから自動生成されている場合、あなたはAPIの成功を自ら妨害していることになります。これは議論の余地があることは知っています。あなたのエンジニアリングチームがSwagger/OpenAPIを愛していることも知っています。それが時間を節約していることも理解しています。しかし、23の異なるAPI製品で開発者の行動を追跡して得た教訓は、 自動生成ドキュメントは人間が作成したドキュメンテーションよりも67%高い放棄率を持っています。

問題は、自動生成ドキュメントが不正確であることではありません—通常は技術的に正しいのです。問題は、間違ったオーディエンスに最適化されていることです。これはAPIを構築したエンジニアのために書かれており、それを使用しようとしている開発者のためではありません。コードが何をするかを説明するだけで、どの問題を解決するかは説明していません。パラメータをリストアップするばかりで、それを使用する理由や、省略した場合に何が起こるかを説明していません。

私はかつて、すばらしいOpenAPI仕様を持つフィンテック企業のコンサルタントをしました。すべてのエンドポイントは文書化されていました。すべてのパラメータにはタイプと説明がありました。しかし、APIが実際に何をするのかを開発者に尋ねると、彼らは答えられませんでした。ドキュメントは、POST /transactionsエンドポイントが「指定されたパラメータを持つトランザクションオブジェクトを作成する」と説明していました。技術的に正しいですが、完全に無意味です。

開発者が実際に知る必要があること： 「このエンドポイントを使用して、顧客からの支払いを記録します。返却されるトランザクションIDを使用して、支払い状況を追跡したり、払い戻しを発行したり、領収書を生成したりします。ほとんどの顧客は、チェックアウトフローから支払い情報を収集した直後にこのエンドポイントを呼び出します。」

違いがわかりますか？1つはコードを説明します。もう1つはソリューションを説明します。自動生成ドキュメントは、その飛躍をすることができません。なぜなら、コンテキストを理解していないからです。あなたのユーザーの80%がeコマースのチェックアウトを構築していることを知らないのです。最も一般的な間違いが、冪等性キーを含めることを忘れることだとも知りません。開発者が通常このエンドポイントをGET /payment-methodsと組み合わせて呼び出す必要があることも知りません。

最良のAPI採用率を持つ企業は、自動生成を出発点として使用し、最終点としては使用しません。彼らはリファレンスドキュメントを生成し、その後、技術作家—または実際にAPIを使用する開発者アドボケート—に、実際のコンテキスト、実際の例、実際のユースケースを持ってすべてのページを書き直させます。それには時間がかかります。費用もかかります。しかし、それは3%のアクティベーション率と40%のアクティベーション率の違いです。

認証ドキュメンテーションのギャップ

私が繰り返し見る最大のドキュメンテーションの失敗を1つ挙げるとすれば、それは認証です。これはほとんどの開発者があきらめる場所です。認証が本質的に複雑だからではありません—そうではなく、ドキュメンテーションが新しいユーザーが持っていない知識を前提としているからです。

「開発者があなたのAPIを10分以内に動作させることができない場合、他のものを見つけるでしょう。あなたの競争相手は1回のGoogle検索の先にいます。」

ここに、私が先月評価したAPIからの実際の例があります。彼らの認証ドキュメントは次のように始まりました: 「TXT1.aiはOAuth 2.0とJWTトークンを使用します。ダッシュボードからクライアント資格情報を取得し、それを使用して認可コードフローでアクセストークンと交換します。」もしあなたが経験豊富なAPI開発者であれば、これは意味がわかるかもしれません。しかし、そうでなければ？あなたは壁にぶつかります。

何が欠けているのか？すべてです。ダッシュボード内のどこにこれらの資格情報があるのでしょうか？認可コードフローとは何ですか？なぜAPIキーを使用する代わりにそれが必要なのでしょうか？成功した認証リクエストはどのようになりますか？応答には何が含まれていますか？トークンの有効期限はどのくらいですか？期限が切れた場合はどうなりますか？初日からリフレッシュロジックを実装する必要がありますか、それともシンプルに始めることができますか？

私は34の異なるAPIのOAuth実装からこのパターンを追跡しました。平均的な認証ドキュメントは1,200語の長さです。最初の成功した認証までの平均時間は？47分。しかし、興味深いことに、最も短く、シンプルな認証ドキュメント（平均400語）を持つAPIは、認証までの最短時間（平均8分）を記録しました。