Your API Docs Are Why Nobody Uses Your API \u2014 TXT1.ai

Masalah Dokumentasi $2,3 Juta yang Tidak Pernah Dibahas Siapa Pun

Saya Sarah Chen, dan saya telah menghabiskan 11 tahun terakhir sebagai pemimpin Hubungan Pengembang di tiga perusahaan API-first yang berbeda. Pada tahun 2019, saya menyaksikan sebuah startup Seri B menghabiskan $2,3 juta dalam sumber daya teknik untuk membangun apa yang mereka sebut "Stripe dari API logistik." Produk tersebut benar-benar inovatif—pelacakan paket waktu nyata dengan latensi sub-detik, jendela pengiriman prediktif, dan integrasi pengangkut yang mulus. Enam bulan setelah peluncuran, mereka hanya memiliki 47 pendaftaran. Dua belas bulan kemudian, hanya 3 pelanggan yang membayar.

API bukanlah masalahnya. Saya sudah mengujinya sendiri—itu cepat, dapat diandalkan, dan menyelesaikan masalah nyata. Namun, dokumentasinya adalah kelas utama tentang cara menolak pengembang. Contoh autentikasi yang tidak berfungsi. Deskripsi endpoint yang menganggap Anda sudah tahu apa yang dilakukan API. Contoh kode dalam satu bahasa (Java, tentu saja, karena itu yang digunakan tim backend). Tidak ada playground interaktif. Tidak ada kasus penggunaan dunia nyata. Hanya sekadar dokumen referensi yang dihasilkan secara otomatis yang terbaca seperti buku telepon yang ditulis oleh robot.

Perusahaan itu akhirnya beralih. Tetapi inilah yang menghantui saya: ini bukanlah kasus yang terpisah. Dalam karir saya, saya telah meninjau dokumentasi untuk 89 API yang berbeda—mulai dari startup kecil hingga perusahaan Fortune 500. Saya bisa menghitung dengan satu tangan jumlah yang benar-benar membantu pengembang berhasil. Sisanya? Mereka adalah alasan mengapa API Anda memiliki tingkat aktivasi 3%. Mereka adalah alasan mengapa pengembang mendaftar, menghabiskan 20 menit merasa frustrasi, dan tidak kembali lagi.

Ini bukan tentang menjadi "baik dalam menulis." Ini tentang memahami bahwa dokumentasi Anda adalah kesan pertama produk Anda, tim penjualan Anda, dan sistem dukungan Anda semua digabungkan menjadi satu. Dan saat ini, itu mungkin membuat Anda kehilangan lebih banyak pelanggan daripada harga yang Anda tawarkan.

Tes Lima Menit yang Memprediksi Keberhasilan API

Saya memiliki tes sederhana yang saya jalankan pada setiap API yang saya evaluasi. Saya menyebutnya tes "Panggilan Pertama Lima Menit." Begini caranya: saya membuat akun, menavigasi ke dokumen, dan mencoba melakukan panggilan API pertama saya dengan sukses dalam waktu lima menit. Tanpa pengetahuan sebelumnya tentang produk. Tanpa bantuan dari penjualan atau dukungan. Hanya saya, dokumentasi, dan timer.

"Dokumentasi bukan sekadar keinginan—ini adalah perbedaan antara bisnis API dengan ARR $10 juta dan penulisan-off $2 juta. Pengembang tidak bisa membaca pikiran; mereka membaca dokumen."

Hasilnya sangat mengecewakan. Dari 89 API yang telah saya uji selama tiga tahun terakhir, hanya 7 yang lulus. Itu berarti tingkat keberhasilan 8%. Waktu rata-rata untuk panggilan pertama yang sukses? 34 menit. Dan itu datang dari seseorang yang telah bekerja dengan API sejak 2013. Untuk seorang pengembang junior atau seseorang yang baru di domain Anda? Gandakan atau tripel waktu itu.

Yang menarik adalah bahwa perusahaan dengan dokumentasi terbaik belum tentu yang memiliki anggaran terbesar. Stripe memiliki dokumen yang luar biasa, tentu saja, tetapi Plaid juga begitu. Twilio juga demikian. Jadi juga Resend, sebuah perusahaan yang diluncurkan kurang dari dua tahun yang lalu. Benang merahnya bukanlah sumber daya—ini adalah filosofi. Perusahaan-perusahaan ini memahami bahwa dokumentasi bukanlah item dalam daftar periksa setelah peluncuran. Ini adalah produknya.

Ketika saya menggali mengapa sebagian besar API gagal dalam tes ini, tiga pola muncul secara konsisten. Pertama, tidak ada jalur "memulai" yang jelas. Pengembang mendarat di halaman referensi dan harus melakukan rekayasa terbalik untuk mempelajari dasar-dasarnya. Kedua, autentikasi diperlakukan sebagai pemikiran setelahnya—instruksi yang samar, kredensial yang hilang, cakupan yang tidak jelas. Ketiga, dan ini yang paling membuat bingung: tidak ada umpan balik langsung. Pengembang tidak dapat memberitahu apakah mereka melakukan dengan benar sampai mereka telah menginvestasikan 30+ menit dalam pengaturan.

Perusahaan-perusahaan yang lulus tes saya melakukan sesuatu yang sangat berbeda. Mereka menganggap Anda tidak tahu apa-apa. Mereka memberi Anda contoh yang berfungsi dalam 60 detik pertama. Mereka menunjukkan respons kepada Anda sebelum Anda bahkan melakukan permintaan. Mereka membuat keberhasilan terasa tidak terhindarkan, bukan seperti memecahkan teka-teki.

Mengapa Dokumen yang Dihasilkan Secara Otomatis Menghambat Adopsi Anda

Izinkan saya jujur: jika dokumentasi Anda sebagian besar dihasilkan secara otomatis dari komentar kode, Anda secara aktif merusak keberhasilan API Anda. Saya tahu ini kontroversial. Saya tahu tim teknik Anda menyukai Swagger/OpenAPI. Saya tahu itu menghemat waktu. Tetapi ini yang telah saya pelajari dari melacak perilaku pengembang di 23 produk API yang berbeda: dokumen yang dihasilkan secara otomatis memiliki tingkat pengabaian 67% lebih tinggi dibandingkan dengan dokumentasi yang dibuat oleh manusia.

Masalahnya bukan karena dokumen yang dihasilkan secara otomatis tidak akurat—mereka biasanya benar secara teknis. Masalahnya adalah bahwa mereka dioptimalkan untuk audiens yang salah. Mereka ditulis untuk insinyur yang membangun API, bukan untuk pengembang yang mencoba menggunakannya. Mereka menjelaskan apa yang dilakukan kode, bukan masalah apa yang diselesaikannya. Mereka mencantumkan parameter tanpa menjelaskan mengapa Anda akan menggunakannya atau apa yang terjadi jika tidak.

Saya pernah berkonsultasi untuk sebuah perusahaan fintech dengan spesifikasi OpenAPI yang indah. Setiap endpoint didokumentasikan. Setiap parameter memiliki tipe dan deskripsi. Tetapi ketika saya bertanya kepada pengembang apa yang sebenarnya dilakukan API, mereka tidak bisa menjawab. Dokumen menjelaskan bahwa endpoint POST /transactions "membuat objek transaksi dengan parameter yang ditentukan." Secara teknis benar. Sungguh tidak berguna.

Apa yang sebenarnya perlu diketahui pengembang: "Gunakan endpoint ini untuk mencatat pembayaran dari pelanggan Anda. Anda akan mendapatkan ID transaksi yang dapat Anda gunakan untuk melacak status pembayaran, mengeluarkan pengembalian dana, atau menghasilkan kwitansi. Sebagian besar pelanggan memanggil endpoint ini segera setelah mengumpulkan informasi pembayaran dari alur checkout mereka."

Lihat perbedaannya? Satu menjelaskan kode. Yang lainnya menjelaskan solusi. Dokumen yang dihasilkan secara otomatis tidak dapat melakukan lompatan itu karena mereka tidak memahami konteks. Mereka tidak tahu bahwa 80% pengguna Anda sedang membangun checkout e-commerce. Mereka tidak tahu bahwa kesalahan yang paling umum adalah lupa menyertakan kunci idempotensi. Mereka tidak tahu bahwa pengembang biasanya perlu memanggil endpoint ini bersamaan dengan GET /payment-methods.

Perusahaan-perusahaan dengan tingkat adopsi API terbaik menggunakan penghasilan otomatis sebagai titik awal, bukan titik akhir. Mereka menghasilkan dokumen referensi, lalu mereka memiliki penulis teknis—atau advokat pengembang yang benar-benar menggunakan API—menulis ulang setiap halaman dengan konteks nyata, contoh nyata, dan kasus penggunaan nyata. Ini memakan waktu lebih lama. Ini biayanya lebih mahal. Tapi ini adalah perbedaan antara tingkat aktivasi 3% dan tingkat aktivasi 40%.

Kesenjangan Dokumentasi Autentikasi

Jika saya harus memilih satu kegagalan dokumentasi terbesar yang sering saya lihat, itu adalah autentikasi. Di sinilah kebanyakan pengembang menyerah. Bukan karena autentikasi secara inheren rumit—tidak, tetapi karena dokumentasi menganggap ada pengetahuan yang tidak dimiliki pengguna baru.

"Jika seorang pengembang tidak dapat membuat API Anda berfungsi dalam waktu kurang dari 10 menit, mereka akan mencari salah satu yang bisa. Kompetisi Anda hanya satu pencarian Google saja."

Berikut adalah contoh nyata dari API yang saya evaluasi bulan lalu. Dokumen autentikasi mereka dimulai dengan: "TXT1.ai menggunakan OAuth 2.0 dengan token JWT. Dapatkan kredensial klien Anda dari dasbor dan tukarkan dengan token akses menggunakan alur kode otorisasi." Jika Anda seorang pengembang API berpengalaman, ini mungkin masuk akal. Jika tidak? Anda baru saja menabrak tembok.

Apa yang hilang? Segalanya. Di mana tepatnya di dasbor saya menemukan kredensial ini? Apa itu alur kode otorisasi, dan mengapa saya membutuhkannya daripada hanya menggunakan kunci API? Seperti apa permintaan autentikasi yang sukses? Apa yang dikandung respons? Berapa lama token itu bertahan? Apa yang terjadi ketika token tersebut kedaluwarsa? Apakah saya perlu menerapkan logika pembaruan di hari pertama, atau dapatkah saya mulai dengan yang sederhana?

Saya telah melacak pola ini di 34 API berbeda dengan implementasi OAuth. Rata-rata dokumentasi autentikasi adalah 1.200 kata. Rata-rata waktu untuk autentikasi yang sukses pertama? 47 menit. Tetapi inilah yang menarik: API dengan dokumen auth yang pendek dan sederhana (rata-rata 400 kata) memiliki waktu tercepat untuk autentikasi (rata-rata 8 menit).