Membuat dokumentasi API dalam Excel atau PDF lalu membagikannya lewat email adalah cara yang sangat familier.
Ketika masalah muncul, kita menghubungi penanggung jawab, mencari email lama, dan memeriksa versi dokumen yang dimiliki pelanggan. Kita menjelaskan kembali perubahan yang ada, mengirim dokumen yang telah diperbarui, lalu memeriksa lagi apakah sudah diterapkan dengan benar.
Karena proses ini sudah terlalu sering kita ulangi, kita jadi menganggapnya sebagai pekerjaan yang memang perlu dilakukan.
Namun masalahnya tidak berhenti pada satu dokumen yang salah.
Setiap kali API berubah, file dan email baru, pengecualian per pelanggan, serta ingatan penanggung jawab bertambah satu per satu. Awalnya hanya ketidaknyamanan kecil, tetapi seiring waktu makin sulit memastikan dokumen mana yang menjadi acuan, dan orang serta waktu yang dibutuhkan untuk menyelesaikan masalah pun ikut bertambah.
Jika pelanggan mengembangkan dengan format request versi lama, akan terjadi error integrasi dan pekerjaan ulang. Jika field wajib atau metode autentikasi disampaikan berbeda, jadwal pengembangan tertunda, dan jika API tersebut sudah beroperasi, hal itu bahkan bisa berujung pada error data atau gangguan layanan.
Baru setelah masalah terjadi, kita menemukan bahwa tim pengembang internal dan pelanggan ternyata melihat dokumen yang berbeda.
Sejak saat itu, developer menghentikan pekerjaan yang sedang berjalan untuk mencari penyebabnya. Tim operasional mencari dokumen lama dan riwayat penyampaian, sementara pelanggan memverifikasi kembali implementasi mereka dan spesifikasi yang diterima. Satu ketidaksesuaian dokumen menghentikan pekerjaan banyak orang sekaligus.
Meski begitu, sebagian besar masalah diselesaikan diam-diam lewat telepon, email, dan messenger.
Ada yang mengirim ulang file yang telah diperbaiki, ada yang menjelaskan situasinya kepada pelanggan, dan developer buru-buru menambahkan penanganan pengecualian. Masalah saat itu terselesaikan, tetapi alasan mengapa masalah terjadi, pelanggan mana yang terdampak, dan apa yang diubah agar masalah yang sama tidak terulang tidak tersisa di organisasi.
Waktu yang digunakan dalam proses ini seharusnya dipakai untuk pengembangan dan peningkatan produk.
Masalah yang lebih besar adalah seluruh proses ini bergantung pada pengalaman, ingatan, dan kotak masuk email penanggung jawab tertentu. Jika penanggung jawab tidak ada di tempat atau keluar dari perusahaan, organisasi harus membongkar email dan riwayat messenger untuk memulihkan kembali pekerjaan.
Dokumentasi API yang tidak dikelola tidak akan menghilang. Ia terus tertinggal di dalam dan di luar organisasi, menjadi utang dokumentasi yang tak terlihat.
Mungkin selama ini kita bukan benar-benar menyelesaikan masalah, melainkan sudah terbiasa menahannya dengan waktu manusia setiap kali masalah muncul.
Setelah mengalami masalah seperti ini dalam pekerjaan nyata, saya membuat SpecBridge.
SpecBridge bukan sekadar alat untuk menulis dokumentasi API. Ini adalah alat operasional dokumentasi API untuk meninjau perubahan dokumen dan mendistribusikan hanya versi yang telah disetujui kepada pelanggan serta mitra eksternal.
Alih-alih menggantikan Swagger yang sudah ada, SpecBridge mengimpor Swagger/OpenAPI dan Postman Collection, lalu berfokus mengelola masalah yang muncul dalam proses penyampaian ke pihak eksternal.
- Membandingkan perbedaan antara versi yang sedang didistribusikan dan versi revisi
- Peninjauan dan persetujuan perubahan
- Memisahkan draf dari versi distribusi yang dilihat pelanggan
- Mengelola cakupan publikasi dokumen per pelanggan
- Mengatur kata sandi dan tanggal kedaluwarsa untuk tautan publik
- Menyediakan dokumen terbaru yang telah disetujui pada tautan yang sama
Tanpa perlu mengirim file baru setiap kali kepada pelanggan, Anda dapat mendistribusikan kembali hanya dokumen yang telah selesai ditinjau secara internal ke tautan yang sudah ada.
Developer dapat mengurangi pekerjaan berulang untuk mencari dan mengirim ulang dokumen, sementara organisasi dapat mengelola dokumentasi API berdasarkan riwayat perubahan dan standar distribusi yang tercatat, bukan berdasarkan ingatan penanggung jawab tertentu.
Saat ini kami mencari partner yang bersedia menggunakan SpecBridge dalam operasional dokumentasi API nyata dan memberikan masukan yang jujur.
Jika tim Anda mengelola dokumentasi API dengan Excel atau PDF, atau harus mengirim ulang dokumen kepada pelanggan setiap kali API berubah, kami ingin memvalidasinya bersama mulai dari satu dokumen yang sedang Anda gunakan saat ini.
Daripada pujian untuk fitur yang dibuat dengan baik, kami ingin mendengar pendapat jujur tentang bagian yang tidak nyaman dalam operasional nyata, prosedur yang tidak perlu, dan fitur yang masih kurang.
Belum ada komentar.