Cách ghi lại thay đổi API bằng quay màn hình

Tài liệu API chủ yếu dựa trên văn bản — tham chiếu endpoint, bảng tham số, tiêu đề xác thực, mẫu mã nguồn. Điều đó là phù hợp. Các lập trình viên làm việc với API cần văn bản dễ quét để đọc và sao chép, chứ không phải một video phải tua đi tua lại.

Nhưng tài liệu thay đổi API có vấn đề khác với tài liệu tham khảo API. Khi một API thay đổi đáng kể — một luồng xác thực mới, thay đổi phá vỡ cách hoạt động của phân trang, cấu trúc payload webhook mới — lập trình viên cần hiểu không chỉ cái gì đã thay đổi, mà còn tại sao, lộ trình di chuyển trông như thế nào và làm sao để xác minh việc triển khai của họ là chính xác.

Đó là nơi quay màn hình đóng một vai trò cụ thể nhưng chưa được tận dụng đúng mức.

Khoảng trống trong tài liệu thay đổi API truyền thống#

Tài liệu thay đổi API tiêu chuẩn bao gồm "cái gì": một mục nhật ký thay đổi mô tả sự thay đổi, tài liệu tham khảo cập nhật hiển thị cấu trúc tham số mới, hướng dẫn di chuyển với các đoạn mã.

Những gì tài liệu này hiếm khi bao quát tốt:

Quy trình làm việc của lập trình viên để di chuyển. Một hướng dẫn di chuyển bằng văn bản mô tả các bước. Một bản quay màn hình cho thấy lập trình viên thực sự mở mã nguồn, tìm các lệnh gọi bị ảnh hưởng, thực hiện thay đổi, kiểm tra trong môi trường sandbox và xác minh phản hồi. Việc trình diễn quy trình đó truyền tải ngữ cảnh mà các đoạn mã đơn thuần không làm được.

Hướng dẫn môi trường kiểm thử. Khi một API phát hành thay đổi quan trọng, lập trình viên cần kiểm tra tích hợp của họ trước khi thay đổi được đưa vào môi trường production. Một bản ghi hướng dẫn cách thiết lập môi trường kiểm thử, các yêu cầu cần chạy, phản hồi mong đợi trông như thế nào và cách diễn giải lỗi giúp giảm đáng kể các phiếu hỗ trợ triển khai.

Trình diễn Postman hoặc curl. Đối với các lập trình viên đang đánh giá tính năng API mới hoặc xử lý thay đổi phá vỡ, việc xem ai đó thực hiện lệnh gọi API, thấy phản hồi trực tiếp và nghe tường thuật giải thích ý nghĩa của từng trường sẽ nhanh hơn so với việc đọc tài liệu endpoint một cách riêng lẻ.

Khi nào quay màn hình tạo thêm giá trị cho tài liệu API#

Không phải tất cả tài liệu API đều hưởng lợi từ video. Tài liệu tham khảo — bảng endpoint, định nghĩa tham số, lược đồ phản hồi — tốt hơn dưới dạng văn bản mà lập trình viên có thể ctrl+F. Video cho nội dung này chỉ lãng phí thời gian của mọi người.

Các danh mục mà quay màn hình tạo ra giá trị thực sự:

Thiết lập xác thực và thông tin đăng nhập. Các luồng xác thực nhiều bước — ủy quyền OAuth 2.0, tạo khóa API, cấu hình bí mật webhook — rất khó mô tả chỉ bằng văn bản. Việc hiển thị trình tự các màn hình giao diện, đầu ra console cần tìm và yêu cầu kiểm tra xác nhận xác thực đang hoạt động giúp giảm đáng kể các phiếu hỗ trợ thiết lập.

Hướng dẫn di chuyển thay đổi phá vỡ. Khi một thay đổi phá vỡ yêu cầu lập trình viên cập nhật tích hợp của họ, một bản ghi hướng dẫn hiển thị lộ trình di chuyển từ triển khai cũ sang mới — với ví dụ mã nguồn hoạt động và phản hồi API trực tiếp — hữu ích hơn hướng dẫn di chuyển bằng văn bản đối với hầu hết lập trình viên.

Hướng dẫn endpoint mới. Khi một khả năng API mới quan trọng được phát hành, một bản ghi hướng dẫn dài 5-8 phút hiển thị endpoint đang được sử dụng — gửi gì, nhận lại gì, các trạng thái lỗi phổ biến, các trường hợp sử dụng thực tế — mang lại sự tự tin cho lập trình viên trước khi họ viết dòng mã tích hợp đầu tiên.

Tài liệu sự kiện Webhook. Payload webhook có thể phức tạp. Một bản ghi hướng dẫn hiển thị webhook đang được kích hoạt, payload thô trong endpoint nhận và cách phân tích các trường liên quan từ đó truyền tải nhiều thông tin hơn một bảng lược đồ JSON.

Thiết lập SDK và lệnh gọi đầu tiên. Đối với các nhóm phát hành SDK client, một bản quay màn hình cài đặt SDK, thực hiện lệnh gọi xác thực đầu tiên và nhận lại phản hồi thực tế giúp giảm ma sát ở phần quan trọng nhất của hành trình lập trình viên — 15 phút đầu tiên.

Phương pháp ghi âm thầm lặng cho nội dung kỹ thuật#

Các bản quay màn hình dành cho lập trình viên có một thách thức cụ thể: người thực hiện ghi âm cần trình diễn mã nguồn và lệnh gọi API thực tế, không chỉ GUI. Điều đó có nghĩa là phải chuyển đổi giữa terminal, trình soạn thảo mã, trình duyệt và có khả năng là một công cụ như Postman.

Vừa làm vừa tường thuật rất khó. Kịch bản đòi hỏi sự chuẩn bị. Ghi lại các lỗi đòi hỏi sự kiên nhẫn.

Các công cụ quay màn hình có tường thuật bằng AI giải quyết vấn đề này. Một lập trình viên hoặc kỹ sư quan hệ lập trình viên ghi lại màn hình của họ một cách thầm lặng trong khi trình diễn quy trình — chạy lệnh trong terminal, thực hiện lệnh gọi API, kiểm tra phản hồi trong Postman, chỉnh sửa mã. Không cần tường thuật trong khi ghi. AI phân tích quy trình và tạo ra tường thuật theo ngữ cảnh giải thích những gì đang xảy ra ở mỗi bước.

Kết quả đầu ra là một bản hướng dẫn có tường thuật nghe như một lập trình viên có năng lực đang giải thích công việc của họ — bởi vì tường thuật được tạo ra từ quy trình thực tế đang được trình diễn, không phải từ một kịch bản mô tả một quy trình giả định.

Kết hợp video với văn bản cho tài liệu thay đổi API#

Tài liệu thay đổi API hữu ích nhất là kết hợp cả hai định dạng:

Thành phần văn bản: mục nhật ký thay đổi (cái gì đã thay đổi và tại sao), tài liệu tham khảo cập nhật (cấu trúc tham số mới, lược đồ phản hồi, mã lỗi) và hướng dẫn di chuyển (hướng dẫn từng bước bằng văn bản với các đoạn mã).

Thành phần video: một bản quay màn hình có tường thuật hiển thị việc di chuyển trong thực tế — thực hiện các lệnh gọi API thực tế, xem các phản hồi trực tiếp, xử lý các trạng thái lỗi phổ biến.

Thành phần văn bản là thứ mà lập trình viên quay lại xem trong khi triển khai. Video là thứ họ xem đầu tiên để hiểu những gì họ sắp triển khai. Những lập trình viên xem video trước sẽ hoàn thành việc di chuyển nhanh hơn và mở ít phiếu hỗ trợ hơn vì họ đã có mô hình tinh thần về quy trình trước khi bắt đầu viết mã.

Giữ cho tài liệu thay đổi API luôn cập nhật#

Tài liệu API có vấn đề về sự lỗi thời cụ thể: nó được đánh phiên bản. Hướng dẫn di chuyển API v2 mô tả một quy trình có thể không còn phù hợp sau khi v3 được phát hành. Việc giữ cho tài liệu cụ thể theo phiên bản được dán nhãn rõ ràng giúp ngăn lập trình viên làm theo các hướng dẫn di chuyển đã lỗi thời.

Đối với các nhóm sử dụng nhúng trực tiếp, tài liệu video cho một phiên bản API cụ thể có thể được đánh phiên bản rõ ràng và lưu trữ khi phiên bản đó bị ngừng hỗ trợ. Các phiên bản mới sẽ có các bản ghi mới thay vì cập nhật các bản hiện có — bảo tồn tài liệu cho các lập trình viên vẫn đang sử dụng các phiên bản cũ hơn trong khi làm rõ lộ trình di chuyển hiện tại.

Xem cách Clevera tạo các hướng dẫn kỹ thuật có tường thuật từ các bản quay màn hình

Một quy trình tài liệu thay đổi API thực tế#

Đối với mỗi thay đổi API quan trọng:

1. Cập nhật tài liệu tham khảo (bảng endpoint, định nghĩa tham số, lược đồ phản hồi)
2. Viết mục nhật ký thay đổi và hướng dẫn di chuyển
3. Ghi lại một bản hướng dẫn màn hình thầm lặng trình diễn lộ trình di chuyển: triển khai cũ, thay đổi, triển khai mới, kiểm tra và xác minh
4. Gửi bản ghi để tạo tường thuật bằng AI
5. Xem lại bản hướng dẫn có tường thuật và xuất bản cùng với hướng dẫn di chuyển bằng văn bản
6. Liên kết video từ mục nhật ký thay đổi, hướng dẫn di chuyển và bất kỳ thông báo cộng đồng lập trình viên nào

Tổng thời gian sản xuất cho thành phần video sử dụng các công cụ quay màn hình AI: 30-45 phút bao gồm cả ghi âm và xem lại. Chi phí thấp đến mức có thể đưa vào quy trình phát hành sprint thay vì coi đó là việc làm thêm sau khi phát hành.