開発者が実際に見るAPIドキュメント動画の作り方

文章で書かれたAPIリファレンスは正確で網羅的ですが、そこから始めるのはほぼ不可能です。エンドポイント一覧にたどり着いた開発者は、各フィールドの意味は分かっても、APIを使い始める最初の5分がどんなものかは分かりません。

その隙間を埋めるのが短い動画です。リファレンスの代わりではなく、その相棒です。実際のキー、実際のリクエスト、実際のレスポンスを見せる3分の動画は、リファレンスには答えられない問いに答えます。自分が思っているとおりに動くのか?

そんな動画を、長く役立つ形で撮る方法をまとめます。

動画にする価値があるものを選ぶ

動画は維持コストが高いものです。テキストが最も弱いところに使いましょう。

• 最初の成功リクエスト: 空のターミナルから200レスポンスまで。作れる動画の中で最も価値が高い一本です
• 認証フロー: OAuthのリダイレクト、トークン交換、リフレッシュ処理は「順序」です。順序こそ動画の得意分野です
• 複数ステップのワークフロー: リソース作成、ステータスのポーリング、結果取得。リファレンスでは無関係な3つのエンドポイントに見えます
• Webhookとコールバック: 2つのシステムがやり取りする様子は、文章で説明するのが本当に難しい領域です
• よくある失敗: 401が出て直すまでの動画は、それについての一段落よりも多くの問い合わせを減らします

動画にすべきでないもの: 個々のエンドポイントのパラメータ、enumの値、レート制限の数値。検索・コピーでき、数秒で更新できるテキストに任せましょう。

収録用サンドボックスを用意する

本番環境に本物のキーで収録しないでください。録画ボタンを押す前に専用環境を作ります。

• 使い捨てのサンドボックスアカウントを使い、キーは収録後すぐにローテーション
• 現実的なデータを入れる: test_user_1 や "foo" はデモを嘘くさくします。もっともらしい名前・金額・タイムスタンプが信頼を生みます
• 短命なキー形式があれば使い、トークンが1フレーム映っても無害にしておく
• シェル環境を確認: env の出力とシェル履歴は、どのコードサンプルよりも多くの認証情報を漏らしてきました
• キャッシュと依存関係を事前に温めておく。インストール作業を収録しないために
• 通知をオフに — 公開動画に映り込んだSlackのプレビューは実際に起きる事故です

サンドボックスでも、すべてのフレームが公開されると考えてください。誰かは必ず一時停止します。

適切なキャプチャ設定を選ぶ

APIデモにはたいてい2〜3の画面が登場します。ターミナル、エディタ、PostmanやInsomniaのようなAPIクライアント、そしてダッシュボード用のブラウザです。

• 画面ごとのウィンドウキャプチャでフレームを絞り、散らかったデスクトップを隠す
• アプリを切り替えるならあらかじめ並べて配置し、両方を含む範囲をエリアキャプチャする。収録中のアプリ切り替えは視聴者を混乱させます
• テキスト中心なら30fpsで十分。低いフレームレートのほうが文字の鮮明さにビットレートを回せます
• ネイティブ解像度で収録 — 後から拡大するのがぼやけの原因です
• フォントは18〜24ptに拡大。モニター上で大げさに見えるくらいが動画ではちょうどよいサイズです

すべてのクリップを同じ構成にする

一貫性があってはじめて、スクリーンキャストの寄せ集めではなく「ドキュメント」になります。信頼できる4段構成はこうです。

1. 目的を一文で: 「顧客を作成して課金します」
2. 認証を見せる: ヘッダー1つでも見せましょう。キーがどこに入るのかを見る必要があります
3. リクエストをその場で組み立てる: 入力するか貼り付けて各フィールドを説明する。そのパラメータが必要な理由を言う
4. レスポンスを声に出して読む: JSONで一度止める。次のステップで使うフィールドを指し示す

そして次を予告して終わります。「この id を課金に使います。次の動画で扱います」

JSONとコードを読みやすくする

多くのAPI動画が失敗するのがここです。リクエストは成功し、レスポンスが画面を埋め尽くし、視聴者は読めない波かっこの壁を見ることになります。

• すべて整形して出力: jq に通すか、クライアントの整形機能を有効にする
• どうでもいい部分は畳む: たいていのAPIクライアントはセクションの折りたたみに対応しています。誰も気にしないメタデータは畳みましょう
• 重要なフィールドにズーム: 肝心な2行へのズーム効果は、どんなナレーションより雄弁です。Recordedなら収録後にエディタでズームを足せるので、収録中はリクエストを正しく行うことに集中できます
• フィールド名はテキストオーバーレイで: subscription_status を指すラベルは、口で言うより速く読まれます
• 待ち時間はカット: ネットワーク遅延、ポーリング、リビルドは無音の時間です。切って、短いキャプションで経過時間を伝えましょう

仕様書ではなく同僚のように話す

形式的な説明はすでにリファレンスにあります。ナレーションでは、ドキュメントが言えないことを言いましょう。

• 「このヘッダーが、みんな忘れるやつです」
• 「はい、任意に見えますがこのフィールドは必須です」
• 「ここで422が出たら、ほぼ日付フォーマットのせいです」

こうしたコメントこそが、ドキュメント動画の本当の成果物です。収録前に3〜4個書き出しておきましょう。正確に入力することに集中していると忘れがちです。

クリップは短くモジュール化する

20分の「API全体ツアー」は、エンドポイントが1つ変わった瞬間に寿命が尽きます。1つのタスクに絞った2〜4分のクリップのほうがずっと長生きし、それを説明するリファレンスの該当箇所のすぐ隣に埋め込めます。

モジュール化は撮り直しやすさでもあります。ペイロードの形が変わったら、長い動画を編集するのではなく90秒のクリップを1本撮り直すだけで済みます。

APIが変わる前提で設計する

ドキュメント動画は、ドキュメントの文章より速く古くなります。最初から織り込んでおきましょう。

• バージョン番号を口頭と画面の両方で示す。古い動画が古いと一目で分かるように
• 古びて見えるUI要素は避ける — ダッシュボードのリニューアルはAPI変更より速く動画を老けさせます
• 書き出しファイルだけでなく元の収録とプロジェクトファイルも保存。再編集が再撮影にならないように
• エンドポイントとバージョンでファイル名を付ける。リリース後に更新対象をすぐ見つけられます
• メジャーバージョンが上がるたびにクリップを見直し、事実と違うものは撮り直す

先の四半期に撮った短くて正直な動画は問題ありません。もう存在しないエンドポイントを自信たっぷりに見せる動画は、信頼を失わせます。

疑問が生まれる場所に置く

最も配置のよいAPI動画は、誰も訪れない専用の動画ライブラリではなく、そのエンドポイントのリファレンスページに直接埋め込まれた動画です。2分を超えるならチャプターやタイムスタンプを付け、動画に出てくるコード全文をプレイヤーの下にコピー可能なテキストで置き、成功レスポンスの場面は短いGIFにしてクイックスタートページに載せましょう。

クイックチェックリスト

• 使い捨てキーのサンドボックスアカウント
• 現実的なシードデータ
• 通知オフ、シェル履歴の整理
• フォント拡大、ウィンドウ配置
• 目的 → 認証 → リクエスト → レスポンスの構成
• 整形済みJSON、重要フィールドにズーム
• 待ち時間のカット
• 画面上のバージョン表示
• 対応するリファレンス箇所への埋め込み
• 動画と並べたコピー可能なコード

リファレンスは何ができるかを伝えます。よい収録は、それが本当に動くことを見せます。そしてたいていそれが、開発者を最初の成功リクエストまで連れていきます。