Làm video tài liệu API mà lập trình viên thực sự chịu xem

Tài liệu tham chiếu API dạng chữ thì chính xác, đầy đủ, nhưng gần như không thể dùng làm điểm khởi đầu. Một lập trình viên mở danh sách endpoint của bạn hiểu rõ từng trường nghĩa là gì, nhưng vẫn không hình dung nổi năm phút đầu tiên dùng API sẽ trông ra sao.

Khoảng trống đó chính là chỗ cho một video ngắn. Nó không thay thế tài liệu tham chiếu mà đi kèm với tài liệu. Ba phút cho thấy một khóa thật, một yêu cầu thật và một phản hồi thật sẽ trả lời được câu hỏi mà tài liệu không trả lời nổi: nó có chạy đúng như mình nghĩ không?

Dưới đây là cách quay những video như vậy để chúng còn hữu ích lâu dài.

Quyết định nội dung nào xứng đáng có video

Video rất tốn công duy trì. Hãy dùng nó ở nơi chữ viết yếu nhất:

• Lần gọi thành công đầu tiên: từ terminal trống đến phản hồi 200. Đây là video có giá trị nhất bạn có thể làm
• Luồng xác thực: chuyển hướng OAuth, trao đổi token và logic làm mới đều là chuỗi thao tác. Video sinh ra là để diễn tả chuỗi thao tác
• Quy trình nhiều bước: tạo tài nguyên, kiểm tra trạng thái, lấy kết quả. Trong tài liệu chúng trông như ba endpoint chẳng liên quan gì nhau
• Webhook và callback: hai hệ thống nói chuyện với nhau là thứ rất khó mô tả bằng văn xuôi
• Các lỗi phổ biến: một video về lỗi 401 và cách khắc phục sẽ giảm nhiều ticket hỗ trợ hơn bất kỳ đoạn văn nào

Những thứ không cần video: tham số của từng endpoint, giá trị enum, con số giới hạn tần suất. Chúng thuộc về văn bản, nơi có thể tìm kiếm, sao chép và sửa trong vài giây.

Chuẩn bị một sandbox để quay

Đừng bao giờ quay trên môi trường production với khóa thật. Hãy dựng một môi trường riêng trước khi bấm Ghi.

• Dùng tài khoản sandbox dùng một lần, và xoay khóa ngay sau khi quay xong
• Nạp dữ liệu thực tế: test_user_1 và "foo" khiến bản demo trông giả tạo. Tên, số tiền và mốc thời gian hợp lý sẽ tạo cảm giác tin cậy
• Chọn định dạng khóa ngắn hạn nếu API có hỗ trợ, để một khung hình lỡ lộ token cũng vô hại
• Kiểm tra môi trường shell: kết quả env và lịch sử lệnh đã làm lộ nhiều thông tin đăng nhập hơn bất kỳ đoạn mã nào
• Làm nóng cache và các gói phụ thuộc để không phải quay cảnh cài đặt
• Tắt thông báo — một bản xem trước Slack lọt vào video đã phát hành là sự cố có thật

Kể cả trong sandbox, hãy coi mọi khung hình đều công khai. Sẽ luôn có người bấm tạm dừng.

Chọn cấu hình quay phù hợp

Một bản demo API thường liên quan hai đến ba bề mặt: terminal, trình soạn thảo, một API client như Postman hoặc Insomnia, và đôi khi là trình duyệt cho bảng điều khiển.

• Quay theo cửa sổ cho từng bề mặt giúp khung hình gọn và che đi màn hình nền bừa bộn
• Nếu buộc phải chuyển ứng dụng, hãy sắp chúng cạnh nhau từ trước rồi quay theo vùng bao cả hai. Alt-tab giữa lúc quay khiến người xem mất phương hướng
• 30fps là đủ cho nội dung nhiều chữ, và tốc độ khung hình thấp hơn dành thêm bitrate cho ký tự sắc nét
• Quay ở độ phân giải gốc — phóng to về sau chính là nguyên nhân gây mờ
• Tăng cỡ chữ lên 18–24pt trong terminal và trình soạn thảo. Cỡ trông quá khổ trên màn hình thường là vừa vặn trong video

Dựng mọi clip theo cùng một cấu trúc

Chính sự nhất quán mới biến một mớ bản ghi màn hình thành tài liệu. Một cấu trúc bốn nhịp đáng tin cậy:

1. Nêu mục tiêu trong một câu: “Chúng ta sẽ tạo một khách hàng và thu tiền.”
2. Cho thấy phần xác thực: dù chỉ là một header cũng phải cho xem. Người xem cần thấy khóa được đặt ở đâu
3. Dựng yêu cầu ngay tại chỗ: gõ hoặc dán rồi đi qua từng trường. Nói rõ vì sao cần tham số đó
4. Đọc to phản hồi: dừng lại ở phần JSON và chỉ vào trường sẽ dùng cho bước tiếp theo

Rồi kết lại bằng việc hé lộ phần sau: “Giá trị id này là thứ ta sẽ dùng để thu tiền — đó là nội dung video kế tiếp.”

Làm cho JSON và mã nguồn dễ đọc

Đây là chỗ hầu hết video API thất bại. Yêu cầu chạy thành công, phản hồi phủ kín màn hình, và người xem chỉ thấy một bức tường dấu ngoặc nhọn không đọc nổi.

• Luôn định dạng đầu ra: đưa qua jq hoặc bật tính năng định dạng trong client
• Thu gọn phần không quan trọng: hầu hết API client cho phép gập các khối. Hãy gập những metadata chẳng ai quan tâm
• Phóng to vào trường then chốt: hiệu ứng zoom vào hai dòng quan trọng có giá trị hơn mọi lời giải thích. Trong Recorded, bạn thêm zoom sau khi quay ở trình biên tập, nhờ vậy lúc ghi hình chỉ cần tập trung gọi API cho đúng
• Dùng lớp chữ chú thích tên trường: một nhãn chỉ vào subscription_status đọc nhanh hơn cả nói ra
• Cắt thời gian chờ: độ trễ mạng, vòng lặp polling và build lại đều là khoảng chết. Cắt bỏ và dùng một dòng phụ đề ngắn cho biết đã trôi qua bao lâu

Kể như một đồng nghiệp, đừng như bản đặc tả

Phần mô tả trang trọng đã nằm sẵn trong tài liệu. Lời thuyết minh của bạn nên nói điều tài liệu không nói được:

• “Đây chính là cái header mà ai cũng quên.”
• “Đúng, trường này bắt buộc dù trông có vẻ tùy chọn.”
• “Nếu ở đây báo 422 thì gần như luôn là do định dạng ngày.”

Chính những lời bình như vậy mới là sản phẩm thật sự của một video tài liệu. Hãy viết sẵn ba bốn câu trước khi quay — lúc tập trung gõ cho đúng rất dễ quên.

Giữ clip ngắn và chia thành mô-đun

Một “tour API đầy đủ” dài hai mươi phút sẽ chết ngay khi một endpoint thay đổi. Các clip hai đến bốn phút gói gọn một tác vụ sống lâu hơn nhiều, và có thể nhúng ngay cạnh đúng mục tài liệu mà nó giải thích.

Chia mô-đun cũng đồng nghĩa dễ quay lại. Khi cấu trúc payload đổi, bạn quay lại một clip chín mươi giây thay vì phẫu thuật cả một video dài.

Lường trước việc API sẽ thay đổi

Video tài liệu cũ đi nhanh hơn tài liệu chữ. Hãy tính đến điều đó ngay từ đầu:

• Nói số phiên bản và hiện lên màn hình để một video lỗi thời trông rõ là lỗi thời
• Tránh những chi tiết giao diện dễ lỗi mốt — một lần thiết kế lại bảng điều khiển làm video già đi nhanh hơn cả thay đổi API
• Giữ lại bản ghi gốc và tệp dự án, không chỉ bản xuất, để việc biên tập lại không biến thành quay lại từ đầu
• Đặt tên tệp theo endpoint và phiên bản để sau mỗi lần phát hành biết ngay cần cập nhật gì
• Rà lại các clip mỗi khi lên phiên bản lớn và quay lại những clip đã sai

Một video ngắn và trung thực từ quý trước thì không sao. Nhưng một video tự tin trình bày endpoint không còn tồn tại sẽ khiến bạn mất uy tín.

Đăng ở nơi câu hỏi phát sinh

Video API được đặt đúng chỗ nhất là video nhúng thẳng vào trang tài liệu của endpoint đó, chứ không phải nằm trong một thư viện video chẳng ai ghé. Với video dài hơn hai phút, hãy thêm chương hoặc mốc thời gian, đặt toàn bộ mã trong video dưới trình phát dưới dạng văn bản sao chép được, và xuất một ảnh GIF ngắn cảnh phản hồi thành công cho trang bắt đầu nhanh.

Danh sách kiểm tra nhanh

• Tài khoản sandbox với khóa dùng một lần
• Dữ liệu mẫu thực tế
• Tắt thông báo, dọn lịch sử shell
• Phóng cỡ chữ, sắp xếp cửa sổ
• Cấu trúc mục tiêu → xác thực → yêu cầu → phản hồi
• JSON đã định dạng, zoom vào trường then chốt
• Đã cắt thời gian chờ
• Nêu phiên bản trên màn hình
• Nhúng cạnh đúng mục tài liệu tương ứng
• Đăng kèm mã nguồn sao chép được

Tài liệu tham chiếu cho lập trình viên biết điều gì là khả thi. Một bản ghi tốt cho họ thấy nó thực sự chạy được — và đó thường là thứ đưa họ đến lần gọi thành công đầu tiên.