Menggunakan Prototipe sebagai Spesifikasi Produk API

Sebagai Manajer Produk Pengalaman Pengembang di SendGrid, saya ditugaskan untuk mengidentifikasi peluang, fitur, dan produk yang melibatkan API kami. Satu hal yang telah saya kerjakan adalah mengidentifikasi metode untuk membuat komunikasi ide produk saya kepada PM, Insinyur, dan pelanggan lain menjadi lebih efektif.

Saya telah belajar bahwa Dokumen Persyaratan Produk (PRD) monolitik adalah cara yang kurang ideal untuk melakukan ini dan bahwa antarmuka yang dapat diuji termasuk informasi yang sama dengan spesifikasi produk akan menjadi alternatif yang kuat. Masalah dengan PRD adalah sering kali berukuran sangat besar dan kebanyakan berupa teks. Terlalu mudah kehilangan tempat atau melewatkan sesuatu yang sangat penting.

Teman-teman kami di UX telah memecahkan masalah ini dengan alat seperti Invision , di mana mereka menyediakan antarmuka yang dapat diklik yang dapat Anda sentuh dan gunakan, daripada dokumen atau gambar rangka yang hanya menjelaskan antarmuka. Karena API adalah antarmuka, kami memerlukan alat yang memungkinkan interaksi dengan spesifikasi secara real time, daripada sekumpulan teks deskriptif dan JSON dalam dokumen.

Mendefinisikan Persyaratan

Seperti apa tampilan antarmuka yang dapat diuji ini sebagai spesifikasi produk? Bagaimana cara kerjanya? Apakah itu ada?

Saat saya membaca Bab 18, “Menciptakan Kembali Spesifikasi Produk,” dari Marty Cagan's Inspired: How to Build Products Customer Love , saya menyadari bahwa saya ingin membagikan alat yang telah saya gunakan yang memenuhi persyaratan Cagan untuk spesifikasi produk, sebagian besar daftar keinginannya untuk spesifikasi produk, dan daftar pribadi saya tentang persyaratan prototipe-sebagai-spesifikasi.

Persyaratan Cagan*:

• Spesifikasi harus menggambarkan pengalaman pengguna secara penuh.
• Spesifikasi harus secara akurat mewakili perilaku perangkat lunak.
• Anda harus dapat mengomunikasikan produk sedemikian rupa sehingga semua pemangku kepentingan mendapatkan apa yang mereka butuhkan.
• Spek akan berubah
• Perlu ada representasi master tunggal dari spesifikasi untuk mengurangi ambiguitas dan versi.

Daftar keinginan Cagan*:

• Anda perlu melengkapi prototipe [dengan]:
  • Logika bisnis
  • Persyaratan rilis
  • Persyaratan pengiriman platform
  • Gunakan kasus
• Saya benar-benar ingin dapat membubuhi keterangan pada prototipe

Persyaratan saya untuk prototipe-sebagai-spesifikasi:

• Prototipe harus spesifikasi.
• Dokumentasi harus diintegrasikan ke dalam prototipe.
• Setiap orang di perusahaan yang membutuhkannya harus memiliki akses ke prototipe dan dokumentasi.
• Pelanggan harus dapat mengakses bagian fungsional dari prototipe untuk pengujian pengguna.
• Prototipe harus menggantikan spesifikasi dan bekerja sedekat mungkin dengan fungsi yang dimaksudkan tanpa memasang kabel pada produk jadi.
• Seharusnya mudah untuk membuat dan mencatat perubahan pada prototipe.
• Harus mudah untuk membuat variasi A/B yang dapat diuji oleh siapa saja yang memiliki akses ke prototipe.
• Seharusnya mudah untuk mengekspor dokumentasi pelanggan dari prototipe.

Memperkenalkan StopLight

Alat yang saya gunakan yang memenuhi hampir semua hal di atas disebut Stoplight.io . Ini pada intinya adalah mesin dokumentasi API dan proxy web. Ini memungkinkan Anda untuk menentukan API Anda menggunakan UI intuitif, yang memiliki yang terbaik dari Swagger dan RAML di belakang layar sebagai mesin spesifikasinya bersama dengan kemampuan untuk mengimpor atau mengekspor dari salah satu format.

Karena StopLight adalah alat dokumentasi, Anda dapat menentukan permintaan, tanggapan, header, dan deskripsi untuk titik akhir Anda. Dengan fitur proxy, Anda dapat memanggil API Anda dan memverifikasi bahwa panggilan Anda sesuai dengan spesifikasi Anda atau menemukan titik akhir secara otomatis untuk membuat sebagian besar dokumentasi Anda ditulis secara otomatis.

Proksi StopLight juga memiliki beberapa fitur luar biasa lainnya:

• Kemampuan untuk melakukan panggilan tiruan ke titik akhir Anda jika produk Anda belum selesai atau Anda tidak ingin mem-proxy permintaan Anda.
• Server lokal untuk menguji prototipe Anda di mesin Anda.
• Server jarak jauh untuk menguji prototipe Anda di Internet.
• Middleware, ditulis dalam Javascript, untuk mendefinisikan kode yang dapat dijalankan sebelum dan/atau setelah titik akhir prototipe Anda dipanggil.

Jika Anda membandingkan kombinasi daftar keinginan saya, persyaratan spesifikasi Cagan, dan daftar keinginannya dengan fungsionalitas yang disediakan StopLight, Anda dapat melihat bahwa StopLight memenuhi setiap kebutuhan dan keinginan:

• Dokumentasi internal saja dari prototipe dan fitur-fiturnya.
• Prototipe lengkap yang mudah diakses dari fungsionalitas.
• Antarmuka yang dapat diuji yang memiliki kemampuan untuk mengaktifkan fitur variabel untuk pengujian dan umpan balik pengguna.
• Cara mudah untuk membuat versi prototipe Anda untuk percakapan tertentu, sehingga Anda dapat memodifikasi fungsionalitas prototipe hampir secara real-time untuk mengilustrasikan dan memverifikasi umpan balik yang Anda terima.

Alur kerja di StopLight sederhana dan dapat dilakukan oleh siapa saja , terlepas dari kemampuan teknis mereka:

• Buat proyek baru.
• Tambahkan spesifikasi dengan mengklik dan mengetik informasi tentang titik akhir, parameternya, permintaan, dan responsnya.
• Tambahkan informasi spesifikasi tentang prototipe Anda di layar Definisi.
• Jika Anda memiliki fitur opsional, tambahkan fitur tersebut menggunakan middleware.
• Aktifkan mengejek.
• Salin/tempel URL publik untuk server yang mengejek dan bagikan ini untuk umpan balik.

Jika Anda akan melakukan kunjungan pelanggan dan ingin bereksperimen dengan prototipe secara real time, cukup unduh definisi ke komputer Anda, buat proyek baru yang dinamai sesuai kunjungan Anda, dan impor definisinya. Sekarang Anda dapat mengubah apa pun yang Anda inginkan tanpa mengubah prototipe asli Anda. Saat Anda kembali dan menggabungkan ide, membuat perubahan semudah membuat prototipe di tempat pertama.

Sebagai Manajer Produk Pengalaman Pengembang, StopLight tidak hanya membantu saya melakukan pekerjaan saya dengan lebih efisien, tetapi juga sangat mudah digunakan, dan membuat langkah persiapan pengiriman untuk mendokumentasikan API menjadi mudah karena dokumentasi dimulai sebelum langkah validasi pelanggan dan diperbarui sepanjang proses. Ada banyak kasus penggunaan dan fitur lain yang disediakan StopLight, tetapi ini mungkin yang paling memengaruhi pekerjaan saya secara signifikan.

*Persyaratan dan daftar keinginan Cagan adalah kutipan langsung dari Inspired: How to Build Products Customer Love.