Apa cara yang efektif untuk mencatat alasan di balik keputusan desain produk?

Di perusahaan kami, kami tidak menggunakan dokumen desain produk apa pun. Kami memiliki total tiga karyawan sehingga semua diskusi desain produk terjadi secara langsung, atau di Slack. (Kami juga menggunakan paket Slack dasar yang hanya memungkinkan melihat pesan terbaru.)

Produk kami masih dalam tahap awal, dan kami sering mengunjungi kembali elemen desain yang diputuskan pada bulan lalu.

Masalah yang sering kita hadapi adalah sering lupa mengapa keputusan desain produk dibuat. Ini menghasilkan berjam-jam terbuang-buang tanah yang sama.

Bagaimana kita dapat secara efektif merekam alasan di balik keputusan desain?

Alur kerja kami didasarkan pada Pelacak Penting. Salah satu solusi yang terjadi pada saya adalah mencatat alasan untuk semua keputusan desain yang relevan sebagai komentar pada cerita pengguna itu sendiri, tetapi ini tampaknya tidak dapat diandalkan.

Untuk menjadi 100% jelas: Saya tidak berbicara tentang desain kode. Saya berbicara tentang desain produk yang diwujudkan oleh kode. Dengan kata lain, saya tidak berbicara tentang keputusan seperti "haruskah kita menyusun kelas ini menggunakan komposisi daripada pewarisan berganda?"; Saya berbicara tentang keputusan seperti "haruskah kami meminta pengguna untuk mengkonfirmasi alamat email mereka sebelum dapat masuk?".

Tujuan dari dokumentasi ini adalah untuk memungkinkan bisnis untuk melihat catatan mengapa keputusan dibuat, untuk membantu dalam membuat keputusan lebih lanjut tentang topik yang sama.

Anda merekam alasan di balik keputusan desain dengan menuliskannya. Idealnya di dekat item yang tunduk pada keputusan (yang bukan "cerita pengguna" - cerita pengguna adalah deskripsi apa yang harus diterapkan, bukan bagaimana).

Itulah terutama komentar dibuat - untuk merekam mengapa sepotong kode tertentu atau struktur terlihat seperti itu (dan saya tidak berbicara secara eksklusif tentang komentar kode). Jika subjek desain Anda adalah fungsi, buat komentar pengantar untuk fungsi tersebut. Jika itu adalah kelas, buat komentar di awal kelas tentang alasannya. Jika Anda memiliki banyak kelas yang semuanya harus mengikuti struktur yang sama, tambahkan dokumen desain terpisah (seperti file "readme") ke paket yang berisi kelas-kelas tersebut. Jika subjek desain Anda adalah diagram UML, tambahkan komentar ke bagian deskripsi diagram.

Dokumen desain IMHO mungkin memiliki nilainya, tetapi jika mereka menggambarkan hal-hal yang terlalu "jauh" dari item yang mereka gambarkan, mereka cenderung menjadi tidak konsisten dengan sangat cepat. Jadi rekomendasi saya adalah meletakkan dokumentasi desain sedekat mungkin dengan barang yang dirancang.

Gunakan dokumen terpisah hanya ketika Anda ingin mendokumentasikan keputusan desain yang mempengaruhi banyak tempat berbeda dari kode Anda secara lintas sektoral. Ketika Anda menggunakannya, cobalah untuk menjadikannya bagian dari basis kode Anda dan letakkan di tingkat hierarki subjek yang dirancang (jadi jika Anda membuat keputusan desain untuk satu modul yang terdiri dari banyak file kode sumber, tempatkan deskripsi desain " di dalam "modul itu, tetapi tidak dalam satu file kelas, bukan pada" deskripsi tingkat atas "yang berlaku untuk modul lain, dan jelas tidak dalam Wiki terpisah di luar SCCS Anda. Jika Anda ingin merekam beberapa" level tinggi ", produk keputusan desain yang luas, maka dokumen tingkat atas mungkin tempat terbaik, tetapi pastikan dokumen ini tetap pada tingkat abstraksi itu.

Pertimbangkan pendekatan yang gesit. Maksud saya, jika Anda memiliki sumber daya waktu dan keterampilan menulis yang sangat baik untuk menuliskan setiap keputusan desain yang Anda buat bersama dengan alasan mereka, cukup dokumentasikan semuanya. Secara realistis, saya berasumsi Anda tidak dalam posisi seperti itu. Pendekatan gesit dapat membantu dengan tantangan utama untuk dokumentasi rasional: Anda sering tidak tahu rasional mana yang penting sampai nanti.

Mari kita mendekati masalah dari sudut pandang holistik. Kalian punya alasan untuk keputusanmu. Mereka terjebak dalam squishyware sekarang, otak tim. Terlepas dari jumlah dokumentasi kredit yang didapat, menyimpan alasan dalam sqishyware tidak terlalu buruk. Kami sebenarnya sangat baik sebagai spesies dalam mengingat hal-hal penting. Itu sebabnya setiap perusahaan besar memiliki "pengetahuan kesukuan," bahkan ketika perusahaan-perusahaan itu berusaha mendokumentasikan semua pengetahuan kesukuan itu.

Sekarang kamu punya masalah. Anda menemukan bahwa sqiushyware tidak memiliki alasan yang cukup baik. Baik untuk Anda karena menyadari ada masalah, dan mengidentifikasi bahwa itu perlu dipecahkan! Itu tidak selalu merupakan langkah yang mudah! Jadi kami cukup yakin solusinya adalah membongkar beberapa alasan itu ke dalam dokumentasi. Namun, itu tidak cukup. Kami tidak pernah bisa melupakan bagian kedua dari teka-teki, yang memuat ulang alasan ke dalam squishyware ketika Anda perlu membuat keputusan. Saya telah melihat banyak tim yang mendokumentasikan semuanya seperti orang gila, tetapi kontennya sebenarnya tidak terorganisir untuk membantu membuat keputusan yang baik, sehingga mereka akhirnya melupakan alasan - alasan meskipun ditulis .

Jadi, Anda memiliki proses dua langkah. Anda perlu mendapatkan alasan keluar dari squishyware dan ke dokumentasi. Maka Anda perlu memastikan bahwa dokumentasi diatur dengan cukup baik untuk mengembalikan rasional ke dalam squishyware saat Anda membutuhkannya! Sekarang saya pikir kita sudah cukup memiliki pernyataan masalah untuk menyadari di mana tantangan akan suka. Ketika Anda mendokumentasikan, Anda biasanya tidak tahu siapa yang akan melihatnya nanti, atau apa yang mereka cari. Demikian juga, ketika Anda melihat kembali pada dokumentasi, Anda biasanya tidak tahu apa yang Anda cari (paling baik Anda tahu kapan).

Jadi perusahaan besar mungkin mencoba menangani ini dalam dua blok besar. Pertama, mereka dapat mengembangkan persyaratan berdasarkan apa yang dibutuhkan orang ketika mereka meneliti dokumentasi. Kemudian mereka menggunakan persyaratan itu untuk membangun proses untuk mengembangkan dokumentasi tersebut. Dan, jika saya berani mengatakan demikian, maka semua orang mengeluh karena hampir tidak ada yang tahu persis seperti apa dokumentasi pada hari pertama. Dokumentasinya selalu tidak lengkap, dan pengembang selalu mengeluh bahwa prosesnya terlalu berat.

Saatnya lincah.

Saran saya adalah memulai upaya tangkas untuk meningkatkan proses dokumentasi Anda: keseluruhan sembilan meter dari squishyware ke dokumen dan kembali ke squishyware. Ketahuilah bahwa Anda akan kehilangan beberapa informasi karena proses Anda tidak sempurna, tetapi tidak apa-apa karena Anda masih mencoba mencari tahu prosesnya! Anda akan kehilangan lebih banyak jika Anda mencoba membuat satu ukuran cocok untuk semua solusi.

Beberapa informasi khusus yang akan saya bahas: * Jelajahi dokumentasi informal. Dokumentasi formal memang bagus, tetapi memakan waktu. Salah satu tujuan dokumentasi adalah merilis informasi dari pengembang squishyware dan menaruhnya di atas kertas. Dokumentasi informal membuat biaya untuk melakukan hal tersebut seminimal mungkin.

• Terima format dokumentasi yang tidak dapat diandalkan. Tidak ada yang benar pertama kali. Lebih baik mendapatkan data dan mencari tahu bagaimana membuatnya dapat diandalkan nanti. Misalnya, Anda dapat mendokumentasikan alasan Anda di blok <rationale> </rationale> atau yang serupa, yang akan memudahkan untuk memanen data itu nanti. Menyimpan alasan dalam cerita pengguna, untuk saat ini, baik-baik saja!
• Jangan pernah lupakan nilai organisasi. Cari tahu bagaimana Anda, sebagai sebuah tim, suka mencari alasan dalam dokumentasi, dan mencoba mendokumentasikannya. Setiap tim akan memiliki proses yang berbeda. Di salah satu tim saya, kami tidak pernah dapat menemukan tiket yang memiliki alasan itu segera. Apa yang bisa kita lakukan adalah menemukan garis kode yang penting, melakukan a svn blameuntuk mencari tahu ketika itu berubah dan mengapa, lalu lihat tiketnya. Setelah kami berada di sana, kami biasanya meletakkan semua alasan yang kami butuhkan tepat di tiket. Itu hanya bekerja untuk kita, cari tahu apa yang cocok untukmu
• Dokumentasi organik dapat tumbuh seiring waktu. Jarang bagi pengembang untuk mengetahui alasan mana yang paling penting pada hari mereka perlu menulisnya. Kami biasanya mencari tahu mana yang penting nanti. Jika Anda memiliki proses perawatan untuk dokumentasi yang memungkinkan pengembang untuk mengelola kebun rasional mereka sendiri, yang penting akan muncul ke permukaan. Yang lebih penting, alasan mungkin berubah. Anda mungkin menyadari bahwa dua perubahan yang berbeda, dengan dua alasan yang berbeda, benar-benar digambarkan oleh satu alasan yang cocok untuk keduanya. Sekarang ada lebih sedikit konten antara Anda dan keputusan!

Saya sarankan menyiapkan instance pribadi MediaWiki atau beberapa perangkat lunak wiki serupa. Sangat mudah untuk mengatur dan mengatur ulang konten di sana, dan Anda dapat menyalin dan menempelkan diskusi baru langsung ke tab diskusi artikel wiki yang relevan. Kami menggunakan MediaWiki di pekerjaan terakhir saya untuk semua arsitektur dan dokumen API kami, dan itu adalah penyelamat.

Pikirkan tentang hal ini dari sudut pandang pembuat kode yang akan diminta untuk mengubahnya dalam waktu 12 bulan.

Jika Anda menambahkan aturan bisnis ini sebagai pengujian otomatis maka perubahan akan dilakukan DAN KEMUDIAN Anda akan mendapatkan dari tes gagal persyaratan yang bertentangan (dan mudah-mudahan Anda menangkap orang yang terkait dengan persyaratan asli dan alasan mereka menentukannya).

Saya menganggap dokumen desain (tempat Anda meletakkan diagram BPMN, diagram Transaksi, bahkan foto papan tulis, dll.) Mirip dengan kode, hanya bentuk yang tidak dapat dieksekusi ... yang berarti apa yang Anda coba catatan mirip dengan komentar kode, tetapi persyaratan (dapat diuji) ditentukan di muka dalam desain. Agaknya jika Anda adalah seorang toko gesit Anda masih merancang kode Anda, Anda cukup melakukannya pada menit terakhir sebelum menulisnya. Simpan ini di basis kode dengan semua dokumen proyek lainnya.

Apa pun yang Anda lakukan, pastikan disimpan dengan cara yang dapat ditelusuri (misalnya Anda mungkin ingin menarik semua aturan bisnis yang terkait dengan "otentikasi" saat menentukan perubahan baru).

Seperti biasa ketika Anda menulis sesuatu, Anda harus bertanya pada diri sendiri siapa audiens yang dituju. Saya sangat percaya bahwa dokumen desain ada untuk pengembang rekan saya, yang saat ini atau yang akan datang. Dokumen ini membantu mereka memahami apa yang saya sedang membangun atau apa yang dibangun (ikhtisar tingkat tinggi) dan yang lebih penting mengapa. Ini adalah tempat untuk mendokumentasikan alternatif yang Anda pertimbangkan, pro dan kontra dari masing-masing.

Mengatakan bahwa tidak masalah bagi beberapa desain untuk hidup dalam otak orang membuat para pengembang pindah dan mencari pekerjaan yang berbeda, membawa serta informasi berharga itu.

Memiliki kode Anda menjadi satu-satunya dokumentasi desain seperti menemukan jalan di sekitar kota menggunakan kaca pembesar. Peta jauh lebih berguna (sayangnya tidak ada GPS yang setara dengan kode sumber).

Saya setuju bahwa desain dokumentasi membusuk lebih cepat daripada kode. Dan karena tidak ada validasi yang mungkin di antara keduanya, satu-satunya hal yang dapat Anda lakukan adalah menjaga mereka tetap berdekatan. IMO, dokumen desain tertanggal masih memberikan informasi berharga.