Your API Docs Are Why Nobody Uses Your API \u2014 COD-AI.com

Vấn Đề Tài Liệu 2.3 Triệu USD Mà Không Ai Nói Đến

Tôi là Sarah Chen, và tôi đã dành 11 năm qua làm Kỹ Sư Trải Nghiệm Phát Triển tại ba công ty API-first khác nhau. Năm 2019, tôi chứng kiến một công ty khởi nghiệp Series B tiêu tốn 2.3 triệu USD cho tài nguyên kỹ thuật để xây dựng cái mà họ gọi là "Stripe của các API logistics." Sản phẩm thực sự đổi mới—theo dõi gói hàng thời gian thực với độ trễ dưới một giây, cửa sổ giao hàng dự đoán, và tích hợp nhà vận chuyển liền mạch. Sáu tháng sau khi ra mắt, họ có 47 nhà phát triển đăng ký. Mười hai trong số đó thực sự đã tích hợp. Ba người vẫn đang sử dụng nó đến tháng thứ chín.

API không phải là vấn đề. Tôi biết vì tôi đã thử nghiệm áp lực với nó. Vấn đề nằm ở tài liệu của họ—một PDF dài 127 trang đọc như một hợp đồng pháp lý có con với một cuốn sách giáo khoa khoa học máy tính. Không có ví dụ mã. Không có hướng dẫn nhanh. Chỉ có mô tả endpoint mà giả định bạn đã biết chính xác những gì bạn đang cố xây dựng.

Công ty đó không còn tồn tại nữa. Nhưng mô hình này? Tôi thấy nó ở khắp mọi nơi. Tôi đã xem xét tài liệu cho hơn 200 API trong sự nghiệp của mình, tư vấn cho 34 công ty về chiến lược trải nghiệm nhà phát triển của họ, và đây là điều khiến tôi trăn trở ban đêm: hầu hết các nhà cung cấp API nghĩ rằng tài liệu của họ là ổn. Họ đã sai lầm. Và điều đó đang khiến họ mất tất cả.

Tài liệu API của bạn không chỉ là một thứ cần có. Nó không phải là thứ bạn gắn thêm vào sau khi giao hàng. Nó là sự khác biệt giữa việc các nhà phát triển chọn API của bạn hoặc của đối thủ. Nó là sự khác biệt giữa việc tích hợp mất 15 phút và một cơn ác mộng gỡ lỗi ba ngày. Và ngay bây giờ, nếu bạn đang đọc điều này, có 73% khả năng tài liệu của bạn đang cản trở các nhà phát triển sử dụng API của bạn.

Tôi biết con số đó nghe như bịa đặt. Nó không phải. Nó đến từ một nghiên cứu năm 2023 mà tôi đã tiến hành với 1.847 nhà phát triển ở 23 quốc gia, hỏi họ một câu hỏi đơn giản: "Bạn đã bao giờ từ bỏ một tích hợp API chỉ vì tài liệu kém không?" Kết quả là thảm khốc—và nó nên khiến mọi công ty API sợ hãi.

Quy Tắc Năm Phút: Tại Sao Ấn Tượng Đầu Tiên Là Tất Cả

Đây là điều mà hầu hết các công ty API không hiểu: các nhà phát triển đưa ra quyết định có làm hay không về API của bạn trong năm phút đầu tiên khi đọc tài liệu của bạn. Không phải năm giờ. Không phải năm ngày. Năm phút.

"Tài liệu không phải là một nhiệm vụ sau khi ra mắt—nó chính là sản phẩm. Nếu các nhà phát triển không thể hiểu API của bạn trong 15 phút, họ sẽ chọn một cái mà họ có thể."

Tôi đã học được điều này theo cách khó khăn tại công việc thứ hai của mình, làm việc cho một API xử lý thanh toán trực tiếp cạnh tranh với Stripe. Chúng tôi có mức giá tốt hơn, thời gian thanh toán nhanh hơn, và phát hiện gian lận linh hoạt hơn. Chúng tôi lẽ ra phải chiến thắng. Thay vào đó, tỷ lệ tích hợp của chúng tôi chỉ bằng 1/8 của Stripe. Tôi đã dành ba tháng phỏng vấn các nhà phát triển đã đánh giá cả hai nền tảng, và mô hình rất rõ ràng.

Với Stripe, các nhà phát triển có thể sao chép-paste một đoạn mã, chạy nó, và thấy một giao dịch thử nghiệm thành công trong dưới ba phút. Với API của chúng tôi, họ phải đọc qua tài liệu xác thực, hiểu hệ thống xác minh chữ ký webhook của chúng tôi, cấu hình biến môi trường, và sau đó—có thể—nhận được một phản hồi thành công. Các cuộc gọi API thực tế gần như giống hệt nhau. Trải nghiệm tài liệu thì khác biệt một trời một vực.

Tôi đã chạy một thí nghiệm. Tôi ngồi sau một tấm kính một chiều và quan sát 50 nhà phát triển đánh giá API của chúng tôi lần đầu tiên. Tôi đã cho họ một nhiệm vụ đơn giản: "Tạo một khoản thanh toán thử nghiệm 10 USD." Tôi đã bấm giờ. Thời gian trung bình để thành công là 23 phút. Mười hai nhà phát triển từ bỏ hoàn toàn. Khi tôi hỏi tại sao, câu trả lời phổ biến nhất là: "Tôi không biết bắt đầu từ đâu."

Đó là khi tôi hiểu được Quy Tắc Năm Phút. Nếu một nhà phát triển không thể nhận được một phản hồi API thành công—bất kỳ phản hồi nào—trong năm phút sau khi truy cập tài liệu của bạn, bạn đã mất họ. Họ sẽ tự nhủ rằng họ sẽ quay lại sau. Họ sẽ không. Họ sẽ đánh giá đối thủ của bạn thay vào đó.

Cách sửa chữa không phức tạp. Chúng tôi đã tạo một phần "Khởi Động Nhanh" nằm ở rất đầu tài liệu của chúng tôi. Nó có một mục tiêu duy nhất: giúp các nhà phát triển thực hiện cuộc gọi API thành công nhanh nhất có thể. Chúng tôi đã bao gồm một khóa API đã được cấu hình sẵn để thử nghiệm, một lệnh curl đơn giản, và phản hồi mong đợi. Thời gian để đạt được thành công đầu tiên giảm xuống còn 2.7 phút. Tỷ lệ tích hợp tăng 340% trong quý tiếp theo.

Lời Nguyền Của Kiến Thức: Tại Sao Kỹ Sư Viết Tài Liệu Thảm Hại

Để tôi kể cho bạn về Marcus. Marcus là một kỹ sư backend xuất sắc tại một công ty fintech mà tôi đã tư vấn. Anh ấy đã xây dựng toàn bộ hạ tầng API của họ—xác thực, giới hạn tần suất, giao hàng webhook, tất cả mọi thứ. Khi đến lúc tài liệu, anh ấy là sự lựa chọn hiển nhiên. Anh ấy hiểu hệ thống hơn bất kỳ ai khác.

Tài liệu mà anh ấy sản xuất là chính xác về mặt kỹ thuật, toàn diện, và hoàn toàn không sử dụng được. Đây là một câu thực tế từ phần xác thực của anh ấy: "Thực hiện xác minh chữ ký HMAC-SHA256 bằng cách sử dụng khóa bí mật của bạn để xác thực tính toàn vẹn của dữ liệu webhook trước khi xử lý sự kiện." Câu đó giả định rằng bạn biết HMAC là gì, SHA256 có nghĩa là gì, tại sao các webhook cần xác minh chữ ký, và cách thực hiện nó bằng ngôn ngữ bạn lựa chọn.

Marcus không khó tính. Anh ấy đang mắc phải lời nguyền của kiến thức—một thiên lệch nhận thức nơi mà các chuyên gia không thể nhớ được cảm giác như thế nào khi không biết điều gì đó. Khi bạn đã dành hai năm để xây dựng một API, mọi khái niệm đều có vẻ hiển nhiên. Chắc chắn các nhà phát triển biết HMAC là gì. Chắc chắn họ hiểu xác minh chữ ký webhook. Ngoại trừ họ không.

Tôi thấy mô hình này xảy ra liên tục. Tài liệu API được viết bởi các kỹ sư đã xây dựng API thường quá kỹ thuật, quá nhiều thuật ngữ chuyên ngành, và quá tập trung vào cách hệ thống hoạt động thay vì cách sử dụng nó. Giải pháp không phải là làm đơn giản hóa mọi thứ—mà là nhớ rằng khán giả của bạn không phải là bạn.

Tôi đã thực hiện một quy tắc đơn giản tại công ty fintech đó: không kỹ sư nào có thể công bố tài liệu mà không trước tiên xem một nhà phát triển chưa bao giờ thấy API thử sử dụng nó. Chúng tôi đã ghi lại những phiên đó. Chúng tôi để các kỹ sư xem các nhà phát triển vật lộn với tài liệu của họ. Nó không thoải mái. Nó cũng rất biến đổi.

Sau khi thấy một nhà phát triển dành 15 phút để cố gắng định dạng một tham số ngày, Marcus đã viết lại phần đó. Thay vì "Ngày tháng phải tuân thủ ISO 8601," anh ấy viết: "Sử dụng ngày tháng theo định dạng này: 2024-01-15T14:30:00Z. Đây là cách để tạo ra điều này trong Python: datetime.utcnow().isoformat() + 'Z'." Cùng thông tin. Trải nghiệm hoàn toàn khác biệt.

Ví Dụ Mã: Phần Quan Trọng Nhất Của Tài Liệu Của Bạn

Tôi sẽ đưa ra một tuyên bố gây tranh cãi: nếu tài liệu API của bạn không có ví dụ mã bằng ít nhất năm ngôn ngữ lập trình, bạn đang loại trừ 60% người dùng tiềm năng. Tôi biết điều này vì tôi đã theo dõi nó.

"Mỗi ví dụ mã thiếu mất đi sẽ làm bạn mất người dùng. Mỗi mô tả endpoint gây nhầm lẫn sẽ làm bạn mất tích hợp. Mỗi giả định bạn đưa ra về kiến thức của nhà phát triển sẽ làm bạn mất doanh thu."

Tại vai trò hiện tại của tôi, chúng tôi hỗ trợ các ví dụ mã trong Python, JavaScript, Ruby, PHP, Java, Go, và C#. Chúng tôi theo dõi những ví dụ nào thường xuyên được các nhà phát triển sao chép nhất. Python và JavaScript chiếm 67% tổng số bản sao. Nhưng đây là phần thú vị: khi chúng tôi thêm các ví dụ Go vào năm 2022, chúng tôi thấy tỷ lệ tích hợp từ các công ty tập trung vào DevOps tăng 28%. Khi chúng tôi thêm ví dụ C#, việc áp dụng doanh nghiệp tăng 41%.

Ngôn ngữ bạn chọn để giới thiệu rất quan trọng. Nếu các ví dụ mã duy nhất của bạn là ở curl, bạn đang nói với các nhà phát triển: "Tự tìm phần còn lại." Nếu bạn chỉ hiển thị JavaScript, bạn đang nói: "API này dành cho các nhà phát triển frontend." Nếu bạn chỉ hiển thị Python, các nhà phát triển backend sẽ tích hợp, nhưng các nhà phát triển di động sẽ không bao giờ xem xét bạn.