製作開發者真正願意看的 API 文件影片

書面的 API 參考文件精確又完整，卻幾乎無法當作起點。開發者打開端點清單，知道每個欄位的意思，卻完全不知道真正開始使用這個 API 的頭五分鐘長什麼樣子。

一段簡短的影片正好補上這個空缺。它不是參考文件的替代品，而是搭檔。三分鐘展示一把真實的金鑰、一個真實的請求與一個真實的回應，回答了文件無法回答的問題：它真的像我以為的那樣運作嗎?

以下是把這類影片拍得長期有用的方法。

先決定什麼值得拍成影片

影片的維護成本很高，要把它用在文字最薄弱的地方。

• 第一次成功呼叫：從空白終端機到 200 回應。這是你能做的最有價值的一支影片
• 認證流程：OAuth 轉址、權杖交換與更新邏輯都是「順序」。順序正是影片擅長的
• 多步驟工作流程：建立資源、輪詢狀態、取得結果。在參考文件裡它們看起來是三個互不相關的端點
• Webhook 與回呼：兩個系統互相通訊的過程，用文字描述實在太難
• 常見錯誤：一段展示 401 以及如何修正的影片，比一整段文字減少的客服單更多

不值得拍成影片的：個別端點的參數、列舉值、速率限制數字。這些該留在文字裡，方便搜尋、複製，幾秒鐘就能更新。

準備一個錄製沙箱

絕對不要拿真實金鑰對著正式環境錄製。按下錄製鍵之前先架好專用環境。

• 使用拋棄式沙箱帳號，錄完立刻輪換金鑰
• 填入有真實感的資料：test_user_1 和 "foo" 會讓示範顯得假。可信的姓名、金額與時間戳會讓觀眾信任這個 API
• 優先選用短效金鑰格式，這樣即使某一格畫面露出權杖也無害
• 檢查你的 shell 環境：env 的輸出與指令歷史外洩過的憑證，比任何程式碼範例都多
• 事先預熱快取與相依套件，別把安裝過程錄進去
• 關閉通知 —— 公開影片裡跳出的 Slack 預覽是真的發生過的意外

即使是沙箱，也要當作每一格畫面都會被公開。總會有人按下暫停。

選擇合適的擷取方式

API 示範通常牽涉兩三個畫面：終端機、編輯器、Postman 或 Insomnia 這類 API 用戶端，有時還有用於後台的瀏覽器。

• 對每個畫面使用視窗擷取，畫面更緊湊，也遮住雜亂的桌面
• 如果必須切換應用程式，請事先並排擺好，再用區域擷取把兩者都框進去。錄製中來回切視窗會讓觀眾迷路
• 以文字為主的內容 30fps 就夠，較低的影格率能把位元率留給更清晰的字元
• 以原生解析度錄製 —— 事後放大正是模糊的來源
• 把字級調到 18–24pt。在螢幕上看起來誇張的大小，在影片裡剛剛好

讓每段影片結構一致

有了一致性，它才像「文件」，而不是一堆零散的螢幕錄影。一個可靠的四段式結構：

1. 用一句話說明目標：「我們要建立一位客戶並向他收費。」
2. 展示認證：就算只有一個標頭也要展示。觀眾需要看到金鑰放在哪裡
3. 現場組出請求：手打或貼上，並逐個欄位講解。說清楚每個參數為什麼存在
4. 把回應唸出來：在 JSON 上停一下，指出下一步會用到的欄位

最後預告下一步：「這個 id 就是我們收費時要用的 —— 那是下一支影片的內容。」

讓 JSON 與程式碼易讀

多數 API 影片正是栽在這裡。請求成功了，回應鋪滿螢幕，觀眾看到的卻是一堵讀不懂的大括號牆。

• 一律格式化輸出：用 jq 管線處理，或開啟用戶端的格式化功能
• 摺疊無關內容：多數 API 用戶端支援摺疊區塊，把沒人在意的中繼資料摺起來
• 對關鍵欄位縮放：給關鍵的兩行加上縮放效果，勝過任何口頭說明。在 Recorded 裡，你可以錄完後在編輯器中加入縮放，這樣錄製時只需專注把呼叫做對
• 用文字覆蓋標註欄位名稱：一個指向 subscription_status 的標籤，比用嘴說讀得更快
• 剪掉等待：網路延遲、輪詢迴圈與重新建置都是空白時間。剪掉它們，用一行簡短字幕交代經過了多久

像同事一樣講解，而不是像規格書

正式的描述在參考頁裡已經有了。你的旁白應該說出文件說不出的話：

• 「這個標頭就是大家最常忘記的那一個。」
• 「對，這個欄位看起來可選，其實是必填。」
• 「如果這裡出現 422，幾乎都是日期格式的問題。」

這類評註才是文件影片真正的產出。錄製前先寫下三四條 —— 一旦專注在正確打字上，它們很容易被忘掉。

保持短小且模組化

一支二十分鐘的「API 完整導覽」，只要一個端點變動就整支報廢。聚焦單一任務的兩到四分鐘短片壽命長得多，而且可以嵌在它所解釋的那一節參考文件旁邊。

模組化也代表容易重錄。當請求主體結構改變時，你只需重錄一段九十秒的短片，而不是圍著一支長影片動手術。

為 API 的變化預作準備

文件影片比文件文字老得更快，一開始就把這點考慮進去：

• 口頭與畫面上都標明版本號，讓過期的影片一眼就看得出過期
• 盡量避開容易過時的介面元素 —— 後台改版讓影片顯老的速度，比 API 變更還快
• 保留原始錄製與專案檔，而不只是匯出成品，這樣重新剪輯不等於重新拍攝
• 依端點與版本命名檔案，發布之後能馬上找到需要更新的內容
• 每次大版本升級時複查所有短片，把已經說錯的重錄一遍

上一季拍的、簡短而誠實的影片沒有問題。但一支信心十足地展示早已不存在的端點的影片，會讓你失去信任。

發布在問題產生的地方

位置最好的 API 影片，是直接嵌在該端點參考頁裡的那一支，而不是躺在沒人造訪的獨立影片庫中。超過兩分鐘就加上章節或時間戳，在播放器下方附上影片中完整、可複製的程式碼，並把成功回應的片段匯出成簡短 GIF 放到快速上手頁。

快速檢查清單

• 使用拋棄式金鑰的沙箱帳號
• 有真實感的預置資料
• 關閉通知，清理指令歷史
• 放大字級，擺好視窗
• 目標 → 認證 → 請求 → 回應結構
• 格式化的 JSON，對關鍵欄位縮放
• 剪掉等待時間
• 畫面上標明版本
• 嵌入對應的參考章節旁
• 影片旁附上可複製的程式碼

參考文件告訴開發者什麼是可能的。一段好的錄製讓他們看到它真的跑得起來 —— 而這通常就是把他們送到第一次成功呼叫的那一步。