Bài 3 — Thiết kế onboarding và first call cho AI API

First call là khoảnh khắc sinh tử

Ở Bài 2 ta xác định TTFC là North Star của onboarding. Bài này biến nó thành thiết kế cụ thể. Nguyên tắc vàng: mỗi bước dev phải làm trước khi thấy kết quả đầu tiên là một điểm có thể rơi rụng. Nhiệm vụ của DX PM là cắt bớt số bước, và làm mỗi bước còn lại càng khó sai càng tốt.

Khung "5 phút đầu tiên"

Hãy thiết kế ngược từ mục tiêu: một dev lạ, chưa từng biết sản phẩm, phải thấy response thành công trong 5 phút. Con đường lý tưởng:

• Vào docs → có ngay quickstart (không cần đăng nhập để đọc).
• Lấy API key nhanh (ít nhất cho phép key test/sandbox không cần thẻ tín dụng).
• Copy một snippet chạy được ngay — có sẵn key placeholder rõ ràng, có cả curl lẫn 1-2 ngôn ngữ phổ biến (Python, JavaScript).
• Chạy → nhận output thật, kèm giải thích output đó nghĩa là gì.

Mỗi bước thừa (tạo project, cấu hình quyền, chọn region, xác minh email trước khi lấy key) là thuế đánh vào TTFC. Hãy tự hỏi từng bước: "Bước này có thật sự bắt buộc ngay bây giờ không, hay có thể hoãn lại sau first call?"

Đặc thù AI: xử lý output không tất định ngay từ quickstart

Vì AI API trả kết quả biến thiên, quickstart phải làm ba việc thêm so với API thường:

• Cho thấy một ví dụ output thực tế (không chỉ schema), để dev biết hình dạng dữ liệu sẽ nhận.
• Chỉ rõ trường nào ổn định, trường nào biến thiên (ví dụ: id, usage.tokens ổn định; content biến thiên).
• Đưa sẵn tham số kiểm soát như temperature, max_tokens, seed (nếu có) để dev hiểu cách làm output ổn định hơn khi cần test.

Ví dụ cụ thể: snippet quickstart tốt

Một snippet DX tốt cho AI API thường có: dòng cài đặt, dòng khởi tạo client với API_KEY từ biến môi trường (dạy thói quen an toàn ngay), một lệnh gọi tối giản, và in ra kết quả kèm chú thích. Kèm theo là câu "Nếu bạn thấy content trong response, bạn đã tích hợp thành công." — một tín hiệu thành công rõ ràng để dev tự xác nhận.

Giảm ma sát ẩn

• Sandbox / free tier không cần thẻ: rào cản thanh toán giết chết TTFC. Cho phép thử trước, trả tiền sau.
• API key có scope mặc định hợp lý: đừng bắt dev cấu hình quyền chi tiết trước lần gọi đầu.
• Thông báo lỗi chỉ đường: nếu dev quên key, trả về 401 kèm câu "Thiếu header Authorization. Lấy key tại <link>." thay vì chỉ Unauthorized.
• Interactive playground: cho dev thử API trên web trước khi viết code — rút ngắn khoảng cách từ tò mò đến thành công.

Onboarding không dừng ở first call

Sau lệnh gọi đầu, dẫn dắt dev tới second call có ý nghĩa: xử lý lỗi, phân trang, streaming, hoặc endpoint thứ hai. Đây là cầu nối tới activation (Bài 2). Một chuỗi "next step" gợi ý ngay dưới quickstart giữ được đà (momentum) của dev.

Khung tư duy: "Progressive disclosure"

Đừng dội toàn bộ khả năng của API vào mặt dev ngay từ đầu. Lộ dần độ phức tạp: quickstart tối giản trước → khái niệm nâng cao (auth chi tiết, rate limit, batching) khi dev cần. Người mới thấy đơn giản, người sâu vẫn tìm được chiều sâu.

Checklist onboarding

• [ ] Dev đọc được quickstart mà không cần đăng nhập chứ?
• [ ] Có snippet copy-chạy-được cho ít nhất curl + 1 ngôn ngữ chứ?
• [ ] Có sandbox/free key không cần thẻ tín dụng chứ?
• [ ] Quickstart có cho thấy output mẫu thật và tín hiệu "thành công" rõ ràng chứ?
• [ ] Có bước "next step" dẫn tới second call chứ?
• [ ] Bạn đã tự chạy quickstart trên máy sạch, tài khoản mới chưa?

Sai lầm thường gặp

• Bắt tạo project/cấu hình region/thêm thẻ trước first call — mỗi bước cắt một mảng dev.
• Snippet dùng biến chưa định nghĩa hoặc thiếu bước cài đặt, khiến copy vào là lỗi.
• Không cho thấy output mẫu, để dev đoán mò hình dạng dữ liệu AI trả về.
• Docs viết cho người đã hiểu hệ thống, dùng thuật ngữ nội bộ mà dev ngoài không biết.
• Quên đo lại: thiết kế xong không kiểm chứng bằng TTFC thực tế trên dev thật.

Onboarding tốt đưa dev tới thành công đầu tiên. Bài sau bàn về thứ khó hơn: thiết kế bản thân API cho một sản phẩm không tất định.