Your API Docs Are Why Nobody Uses Your API \u2014 COD-AI.com

誰もが語らない230万ドルの文書化の問題

私はサラ・チェンです。これまで11年間、3つの異なるAPIファースト企業で開発者体験エンジニアとして働いてきました。2019年、私はシリーズBのスタートアップが「物流APIのStripe」と呼ぶものを作るために230万ドルのエンジニアリングリソースを費やすのを見ました。この製品は本当に革新的で、サブ秒のレイテンシでのリアルタイムパッケージ追跡、予測配送ウィンドウ、シームレスなキャリア統合を提供していました。ローンチから6ヶ月後、47人の開発者がサインアップしました。実際に統合したのは12人で、9ヶ月後に使用していたのは3人だけでした。

API自体に問題はありませんでした。私が自分でストレステストを行ったからです。問題は彼らの文書でした。127ページのPDFは、法律契約とコンピュータサイエンスの教科書が結婚したようなものでした。コード例はありませんでした。クイックスタートガイドもありません。ただ、あなたが何を構築しようとしているのかをすでに理解していると仮定したエンドポイントの説明がありました。

その会社はもう存在しません。しかし、このパターンは？どこにでも見られます。私のキャリアで200以上のAPIの文書をレビューし、34社の開発者体験戦略に関してコンサルティングを行ってきましたが、私を眠れぬ夜を過ごさせるのはこれです: ほとんどのAPIプロバイダーは自社の文書が良好だと思っています。彼らは間違っています。そして、それは彼らのすべてを奪っています。

あなたのAPI文書は単なる「あっても良い」ものではありません。出荷後に付け加えるものではありません。開発者があなたのAPIを選ぶか、競合他社のAPIを選ぶかの違いです。15分の統合と3日間のデバッグの悪夢の違いです。そして今、あなたがこれを読んでいるなら、あなたの文書が開発者があなたのAPIを使用するのを積極的に妨げている可能性が73%あります。

その数字が作り話のように聞こえることはわかります。しかし、そうではありません。これは、私が2023年に23カ国の1,847人の開発者に対して行った研究から来ています。「悪い文書のためにAPI統合を放棄したことがありますか？」と簡単な質問をしました。その結果は破壊的で、すべてのAPI会社に恐怖を抱かせるべきです。

五分ルール: 初対面がすべてである理由

ほとんどのAPI会社が理解していないことがあります: 開発者は、文書を読み始めてから最初の5分間であなたのAPIの利用可否を決定します。5時間ではありません。5日ではありません。5分です。

「文書はローンチ後の作業ではなく、それ自体が製品です。開発者が15分以内にあなたのAPIを理解できなければ、彼らは理解できるものを選びます。」

私はこのことを、私の2つ目の仕事で、Stripeと直接競合する決済処理APIのために働いていたときに痛感しました。私たちはより良い料金、より迅速な決済時間、より柔軟な不正検知を提供していました。私たちは勝つべきでした。しかし、私たちの統合率はStripeの8分の1でした。両方のプラットフォームを評価した開発者にインタビューを行うことに3ヶ月を費やし、そのパターンは明確でした。

Stripeでは、開発者はコードスニペットをコピーして貼り付け、実行し、3分未満で成功したテストトランザクションを確認できました。私たちのAPIでは、認証の文書を読み、ウェブフック署名検証システムを理解し、環境変数を構成し、その後—おそらく—成功した応答を得る必要がありました。実際のAPIコールはほぼ同じでしたが、文書の体験は天と地ほど違いました。

私は実験を行いました。私は一方向のガラスの向こうに座り、50人の開発者が初めて私たちのAPIを評価するのを見ました。私は彼らにシンプルなタスクを与えました: 「10ドルのテスト支払いを作成してください。」時間を測りました。成功までの平均時間は23分でした。12人の開発者は完全にあきらめました。なぜかを尋ねたとき、最も一般的な反応は「どこから始めればいいかわからなかった」とでした。

これが私が五分ルールを理解した瞬間です。もし開発者があなたの文書にたどり着いてから5分以内に成功したAPI応答—何らかの応答—を得られないなら、あなたは彼らを失ったことになります。彼らは後で戻ってくると言い聞かせますが、戻ってきません。彼らはその代わりに競合他社を評価します。

修正は複雑ではありませんでした。私たちは文書の最初の部分に「クイックスタート」セクションを作りました。その唯一の目標は、開発者ができるだけ早く成功したAPIコールにたどり着くことです。テスト用に事前設定されたAPIキー、単一のcurlコマンド、期待される応答を含めました。最初の成功までの時間は2.7分に短縮されました。次の四半期での統合率は340%増加しました。

知識の呪い: なぜエンジニアはひどい文書を書くのか

マーカスについてお話ししましょう。マーカスは、私がコンサルティングを行っていたフィンテック企業の優れたバックエンドエンジニアでした。彼は彼らのAPIインフラ全体—認証、レートリミティング、ウェブフック配信、すべてを構築しました。文書化の際、彼は当然の選択肢でした。彼はそのシステムを誰よりもよく知っていました。

彼が作成した文書は技術的に正確で、包括的でしたが、全く使えませんでした。彼の認証セクションからの実際の文は次の通りです: 「イベントを処理する前にWebhookペイロードの完全性を検証するために、HMAC-SHA256署名検証を実装してください。」その文は、あなたがHMACとは何か、SHA256とは何か、なぜウェブフックに署名検証が必要なのか、そしてそれを自分の好きな言語で実装する方法を理解していると仮定しています。

マーカスは難しくしているわけではありませんでした。彼は知識の呪いに苦しんでいました—専門家が何かを知らなかった時のことを思い出せない認知バイアスです。APIを構築するのに2年を費やすと、すべての概念が明白に感じられます。もちろん開発者はHMACが何かを知っているはずです。もちろん彼らはウェブフック署名検証を理解しているはずですが、そうではありません。

私はこのパターンを常に見ています。APIを構築したエンジニアによって書かれたAPI文書は、ほとんど常に技術的すぎて、専門用語が多すぎて、システムがどのように機能するかに焦点を当てすぎています。解決策は、物事を簡略化することではなく、あなたの聴衆があなた自身ではないことを忘れないことです。

私はそのフィンテック企業でシンプルなルールを実施しました: どのエンジニアもAPIを初めて使おうとする開発者を見ることなしに文書を公開してはならない。私たちはこれらのセッションを記録しました。私たちはエンジニアに、自分たちの文書に苦しむ開発者を観察させました。それは不快でしたが、同時に変革的でした。

開発者が15分間日付パラメータのフォーマットを理解しようとするのを見た後、マーカスはそのセクションを書き直しました。「日付はISO 8601準拠でなければならない」の代わりに、「日付はこのフォーマットで使用してください: 2024-01-15T14:30:00Z。これはPythonで生成する方法です: datetime.utcnow().isoformat() + 'Z'。」同じ情報ですが、全く異なる体験です。

コード例: あなたの文書の最も重要な部分

私は物議を醸す発言をします: あなたのAPI文書に少なくとも5つのプログラミング言語でコード例がない場合、あなたは60%の潜在ユーザーを排除しています。私はそれを追跡しました。

「欠落したコード例はすべてユーザーを失います。混乱を招くエンドポイントの説明は、すべて統合を失わせます。開発者の知識に関するすべての仮定は、収益を失わせます。」

私の現在の役割では、Python、JavaScript、Ruby、PHP、Java、Go、C#のコード例をサポートしています。開発者が最も頻繁にコピーする例を追跡しています。PythonとJavaScriptが全コピーの67%を占めています。しかし、興味深いことに、2022年にGoの例を追加したとき、DevOpsに焦点を当てた企業からの統合が28%増加しました。C#の例を追加したとき、企業の採用は41%増加しました。

選択した言語は重要です。唯一のコード例がcurlにある場合、あなたは開発者に「残りを自分で見つけてください」と言っていることになります。JavaScriptだけを示す場合、「このAPIはフロントエンド開発者のためのものです」と言っています。Pythonだけを示す場合、バックエンド開発者は統合しますが、モバイル開発者は検討すらしないでしょう。