Desain dokumen sebagai bagian dari Agile

25

Di tempat kerja saya, kami menghadapi tantangan karena "gesit" terlalu sering berarti "persyaratan yang tidak jelas, kriteria penerimaan yang buruk, semoga sukses!" Kami mencoba mengatasinya, sebagai upaya peningkatan umum.

Jadi, sebagai bagian dari itu, saya mengusulkan agar kami membuat dokumen desain yang, di atas dan di luar tingkat cerita pengguna, secara akurat mencerminkan hasil investigasi awal dari efek fitur yang diberikan dalam sistem dan termasuk jawaban atas pertanyaan yang kami miliki. tanya bisnis itu.

Apakah ada standar yang efektif untuk ini?

Kami saat ini menghadapi situasi di mana fitur baru dapat berdampak pada banyak area dalam sistem "bola besar lumpur" kami , dan perkiraan mulai naik karena hutang teknis ini. Semoga proses desain yang lebih bijaksana dapat membantu.

design agile documentation asthasr
sumber

4

solusi tangkas untuk ini adalah komunikasi. Orang yang bertanggung jawab untuk mengetahui APA harus selalu dapat diakses oleh pengembang untuk konsultasi. Selain itu, Anda harus melakukan tes unit dan sering melakukan refactoring untuk menjaga "bola besar lumpur" tetap terkendali.

Euforia

3

Saya tahu bahwa kita harus memiliki hal-hal itu. Kami tidak. Saya mencoba membantu kami sampai di sana, dan saya mencoba melembagakan kerangka kerja komunikasi yang andal dan dapat diulangi (dokumen adalah komunikasi, setelah semua). Masalahnya adalah, sekarang kita menjadi berat "selesaikan sekarang!" siklus, dan kami mengandalkan komunikasi ad hoc yang menghasilkan orang memiliki silo pengetahuan karena tidak ada referensi untuk informasi nyata tentang fitur yang muncul setelah cerita pengguna.

asthasr

4

Agile tidak bertentangan dengan dokumentasi - itu bertentangan dengan dokumentasi yang tidak berguna. Tuliskan sebanyak mungkin dokumentasi yang Anda butuhkan, dan tidak lebih. Khususnya, perlu diingat bahwa dokumentasi hanya referensi ke model mental yang Anda (tim) miliki di kepala Anda. Yang terakhir adalah hal yang sangat penting - namun, Anda tidak dapat sepenuhnya mendokumentasikannya. Sebagai gantinya, tetap disinkronkan melalui banyak komunikasi, dan tulis hanya cukup referensi untuk memastikan bahwa model tetap konsisten dalam jangka panjang.

Péter Török

Saya pikir Anda harus mengajukan pertanyaan yang berbeda dari ini. Untuk pertanyaan seperti ini, Anda akan mendapatkan "dokumen baik-baik saja bila ...", yang tidak akan banyak membantu Anda. Anda harus menanyakan apakah solusi Anda untuk masalah Anda benar dan bertanya tentang kemungkinan solusi lain.

Euforia

4

"Agile tidak bertentangan dengan dokumentasi - itu bertentangan dengan dokumentasi yang tidak berguna.": Setiap proses pengembangan bertentangan dengan dokumentasi yang tidak berguna (sesuai dengan definisi mereka tentang berguna dan tidak berguna).

Giorgio

18

"Persyaratan yang tidak jelas, kriteria penerimaan yang buruk, semoga berhasil!"

yup, ini adalah persyaratan yang sama dengan yang Anda dapatkan bahkan jika Anda mencoba untuk menyelesaikannya juga! (sebagai contoh, dokumen persyaratan 10.000 yang membutuhkan klien pemerintah 4 tahun untuk dibuat masih penuh dengan ketidakkonsistenan, ketidakjelasan, dan bahkan pernyataan yang bertentangan secara internal. Jika 4 tahun dokumentasi persyaratan tidak dapat membuat Anda mendapatkan persyaratan yang layak, tepat, perlu dilakukan, Anda pernah berpikir Anda akan bisa mendapatkan sesuatu yang tidak kabur?)

Jadi ... cara lincah diciptakan untuk memahami bahwa ini tidak terjadi dan bekerja dengannya daripada mencoba untuk melawannya.

Anda mulai dengan bertanya "apa yang Anda inginkan" dan pelanggan menjawab dengan "sesuatu yang seperti ini". Anda melakukan beberapa pekerjaan dan kemudian kembali ke pelanggan dan berkata "apakah ini seperti yang Anda inginkan?", Dan pelanggan biasanya mengatakan "ya tapi ..." di mana Anda bertanya "apa yang Anda inginkan".

Akhirnya Anda mendapatkan persis apa yang diinginkan pelanggan, bahkan jika mereka tidak tahu apa itu! (Sial, mereka tidak pernah tahu apa yang mereka inginkan, tidak persis).

gbjbaanb
sumber

Anekdot dokumen desain pemerintah itu menarik, apakah ada sumbernya? Atau hanya sesuatu yang Anda alami sendiri?

user145400

@ user145400 sesuatu yang saya alami :-(

gbjbaanb

13

Di tim kami, sejak mulai gesit, kami juga telah berusaha mempersempit dan memahami betapa banyak dokumentasi yang sebenarnya diperlukan. Saya dapat membagikan kepada Anda apa yang telah kami pelajari sampai sekarang.

Sebelum ada yang lain, pastikan untuk membaca artikel ini tentang Agile / Lean Documentation . Sangat bagus dibaca.

Kedua, saya akan sangat menyarankan Anda untuk mempertimbangkan kembali memproduksi dokumen desain setelah pekerjaan pendahuluan pada cerita. Kami telah mencobanya sebelumnya dan terbukti sia-sia. Di tengah rilis terakhir kami telah memutuskan untuk memperbarui dokumen desain HANYA SETELAH kode untuk cerita disampaikan. Dan sekarang saya berpikir bahwa itu terlalu cepat.

Anda perlu bertanya pada diri sendiri mengapa Anda ingin melakukan dokumen desain sebelum pengkodean. Bagi kami ini adalah alasannya:

Kita sebagai tim perlu memahami bagaimana cerita akan memengaruhi desain.
Memiliki dokumen desain terbukti bermanfaat ketika anggota baru (atau sementara) bergabung dengan tim atau ketika kembali ke kode yang belum pernah dikerjakan oleh siapa pun selama lebih dari setahun. Jadi mereka berguna untuk memori organisasi untuk membantu memahami cara kerja kode.
Dokumen desain berguna untuk teknisi pemeliharaan yang mungkin perlu memecahkan masalah kode setelah rilis.

Untuk memuaskan (1) Anda tidak perlu membuat dokumen desain yang sebenarnya. Tim Anda masih harus memiliki fase desain sebelum pengkodean, tetapi fase itu dapat sesederhana sesi 15 menit di depan papan tulis atau serbet. Anda tidak perlu membuat dokumen aktual yang akan memakan waktu berjam-jam (jika bukan hari) untuk menulis hanya untuk membahas perubahan desain.

(2) atau (3) tidak diperlukan selama pengembangan cerita saat ini dan lebih dari itu mereka tidak akan diperlukan untuk beberapa iterasi berikutnya.

Juga perlu diingat bahwa setiap kali anggota tim menulis / memperbarui dokumen desain, saat itulah kode tidak ditulis. Ketika Anda menulis dokumen sebelum kode aktual, ada hampir 100% kemungkinan bahwa mereka akan perlu diperbarui karena begitu Anda memulai desain pengkodean selalu berakhir diubah. Dan bahkan jika Anda menulis dokumen desain setelah kode, seperti yang dipelajari oleh tim kami, refactoring dari cerita selanjutnya masih mengubah desain.

Jadi apa yang akan saya rekomendasikan:

Awalnya, buat desain / model sementara cukup sehingga tim Anda dapat memiliki percakapan yang cerdas sebelum pengkodean. Jangan berharap menyimpan ini dan jangan buang waktu untuk memformalkannya.
Hanya buat dokumentasi desain resmi jika seseorang membutuhkannya (mis. Tim Anda memiliki kebutuhan nyata akan memori organisasi)
Hanya menghasilkan dokumentasi desain pada kode yang telah distabilkan. Tidak ada gunanya mencoba mendokumentasikan modul yang terus berubah di setiap iterasi.
Menghasilkan dokumen desain yang sepenuhnya menggambarkan modul (atau bagian dari produk). Di masa lalu kami biasa menulis dokumen desain yang mendokumentasikan perubahan yang harus dilakukan. Dokumen-dokumen itu benar-benar tidak berharga segera setelah pembebasan dilakukan.
Simpan dokumen dengan sangat tinggi. Jika Anda menulis 20 halaman yang mencakup arsitektur dan desain tingkat tinggi, dokumen itu akan a) benar-benar dibaca oleh orang lain dan b) akan membantu orang mengenal tata letak umum kode Anda. Untuk lebih jelasnya, orang bisa langsung masuk ke kode. Jika Anda menulis 700 halaman dengan spesifikasi terperinci, mereka akan hampir selalu tidak cocok dengan kenyataan, itu terlalu banyak bagi siapa pun untuk membaca dan Anda akhirnya harus memelihara dan memperbarui 700 halaman alih-alih 20 setiap kali perubahan di masa depan dibuat.

DXM
sumber

Apa yang Anda katakan tampaknya mirip dengan apa yang saya coba sampaikan; kami memiliki bola lumpur yang rumit, dan saya ingin dokumen sederhana yang a) mengomunikasikan maksud bisnis dari fitur tertentu (yaitu cerita pengguna yang rumit, dengan pertanyaan dijawab); b) tunjukkan bagian mana dari kode dan API yang ada yang akan terpengaruh; dan c) diperlakukan sebagai artefak satu kali, bukan sesuatu yang harus diperbarui dengan setiap fitur baru, selamanya. Mengatakan 20 halaman adalah "level tinggi" menarik bagi saya - kami bahkan tidak memiliki itu. :)

asthasr

@syrion: Berdasarkan apa yang baru saja Anda katakan, sepertinya Anda ingin mendokumentasikan secara rinci setiap cerita dan menghasilkan dokumen "celah desain" (yaitu menentukan perbedaan antara apa yang ada dalam kode hari ini dan apa yang akan ada dalam kode setelah cerita selesai). Apakah Anda memiliki audiensi untuk dokumen seperti itu? Dari pengalaman saya, saya memprediksi tidak ada yang akan membacanya. Pengembang bekerja pada cerita hari sudah tahu apa yang perlu perubahan (mereka baik menulis dokumen atau bagian dari diskusi awal). Dan jika Anda mencoba untuk menangkap SEMUA detail perubahan yang akan Anda buat untuk sebuah cerita, ...

DXM

... Anda akan menghabiskan lebih banyak waktu menulis dokumentasi daripada menulis kode. Dan begitu cerita selesai, seperti yang Anda katakan ini adalah artefak satu kali. Jadi mengapa Anda harus memproduksinya?

DXM

karena saat ini kita memiliki lingkungan yang penuh dengan silo pengetahuan. Kami memiliki orang-orang yang tahu subsistem A karena mereka menulis, dan B karena mereka membantu dukungan ketika itu lalu meledak, tetapi tidak pernah menyentuh C dan D telah ditulis ulang sejak. Sulit bagi pemula dan kontraktor luar untuk masuk atau tetap dalam lingkaran.

asthasr

@syrion: sepertinya Anda memiliki kebutuhan yang sama dengan yang kami miliki. Namun, saya bingung ketika Anda mengatakan Anda ingin dokumen sederhana yang ... diperlakukan sebagai artefak satu kali. Jadi misalkan Anda memiliki layer yang berbicara ke DB dan 6 cerita yang membutuhkan perubahan pada layer itu. Apakah Anda berencana untuk menghasilkan 6 dokumen berbeda bersamaan dengan setiap cerita? Atau Anda ingin memiliki satu spesifikasi desain tunggal untuk lapisan DB? Namun, spesifikasi tunggal adalah sesuatu yang harus diperbarui dengan setiap fitur yang menyentuh lapisan DB.

DXM

3

"Mantra" Agile tidak dapat dilakukan tanpa dokumentasi sepenuhnya.

Mantra Agile adalah untuk memilih " Bekerja perangkat lunak daripada dokumentasi yang komprehensif ". Tetapi perhatikan bit di bagian bawah manifesto.

Artinya, sementara ada nilai di item di sebelah kanan , kami lebih menghargai item di sebelah kiri. "

Paman Bob memiliki kebijakan yang baik untuk dokumentasi

Tidak menghasilkan dokumen kecuali kebutuhannya mendesak dan signifikan .

Anda benar bahwa beberapa orang menggunakan Agile sebagai alasan untuk tidak membuat dokumentasi, tapi itu Agile buruk. Mengabaikan bit yang saya soroti dalam tanda kutip di atas.

Semua yang dikatakan, ketika Anda mengatakan 'saat ini kami menghadapi situasi di mana fitur baru dapat berdampak pada banyak area dalam sistem "bola besar lumpur" kami, jika Anda ingin menjadi gesit, Anda perlu melakukan sesuatu tentang hal ini.

Ketika Anda memiliki dokumentasi, gunakan untuk memodernisasi kode Anda. Dengan cara itu Anda menghapus kebutuhan jangka panjang untuk mempertahankan dokumentasi (yang tidak akan terjadi) dengan menghapus kebutuhan jangka panjang untuk dokumentasi.

yaitu. Buat kebutuhan segera dan signifikan.

pdr
sumber

Jawaban ini "benar", tetapi tidak benar-benar berpikir lebih dari itu. Bagaimana dengan desain arsitektur misalnya? Bagaimana dengan pergantian pengembang / bisnis? Bagaimana ini ditangani oleh banyak tes unit berkualitas?

Paul

@ Paul: Adalah ide bagus untuk memiliki diagram arsitektur SANGAT tingkat tinggi, bersama dengan standar pengkodean yang sangat ringan, untuk pendatang baru. Saya telah menemukan bahwa cara yang baik untuk menjaga agar dokumen-dokumen tersebut tetap mutakhir adalah dengan menyimpannya di wiki dan meminta setiap pendatang baru untuk memutakhirkan di mana mereka menemukan bahwa itu adalah tanggal. Tetapi pertanyaan ini adalah tentang dokumen desain muka secara khusus.

pdr

Saya masih mendukung apa yang saya katakan. Ubah Arsitektur ke apa pun bisnis ingin menyebutnya, dan ubah unit test menjadi tes regresi (otomatis?) Dan itu berlaku.

Paul

@ Paul: Maaf, saya tidak mengikuti. Menurut Anda, dokumen berharga apa yang saya sarankan tidak baik?

pdr

0

Yang lincah adalah bahwa upaya dokumentasi benar-benar harus didorong oleh tim scrum. Jika pengembang tidak merasa dokumentasi eksternal cukup untuk kebutuhan mereka, cerita pengguna akan diblokir sampai mereka melakukannya. Jika bisnis merasa pengembang tidak menghasilkan dokumentasi yang memadai, pemilik produk bersikeras menjadikannya bagian dari kriteria penerimaan. Karena itu, saya benar-benar menemukan dokumentasi kami lebih fokus dan efektif sejak pindah ke scrum.

Kami menggunakan VersionOne untuk melacak cerita pengguna kami, tetapi saya yakin metode kami berlaku untuk sistem lain. Ini memungkinkan Anda melampirkan file ke cerita pengguna. Kami telah menemukan bahwa menjadi tempat yang sangat berguna untuk meletakkan dokumen desain.

Untuk satu contoh yang bekerja sangat baik bagi kami, kami harus menguji desain papan sirkuit baru secepat mungkin setelah prototipe dibangun. Kami membuat dua kisah pengguna untuk semua yang membutuhkan pengujian: satu untuk merancang tes dan satu untuk melaksanakan tes. Salah satu kriteria penerimaan untuk cerita desain adalah bahwa prosedur tes sepenuhnya didokumentasikan dalam cerita eksekusi.

Ketika kami sampai di bagian pengujian, itu berjalan lebih lancar dari yang pernah saya lihat. Kami baru saja membuka kisah pengguna dan mengikuti prosedur langkah demi langkah. Dokumentasinya persis seperti yang kami butuhkan untuk menyelesaikan cerita, tidak lebih dan tidak kurang.

Kami memiliki cerita lain di tumpukan kami hanya untuk meningkatkan dokumentasi untuk chip yang kami gunakan, agar lebih mudah bagi tim lain untuk mengambilnya untuk produk mereka sendiri.

Singkatnya, jika Anda merasa dokumentasi Anda menderita, solusinya semudah membuat cerita pengguna yang terpisah untuknya, dan / atau menjadikannya bagian dari kriteria penerimaan.

Karl Bielefeldt
sumber

0

Ketika Anda berbicara tentang persyaratan yang buruk, hal pertama yang terlintas dalam pikiran saya adalah memastikan Anda memiliki kriteria pengujian. Jika memungkinkan, buat beberapa kasus uji otomatis yang dapat digunakan kembali untuk bagian sistem yang ada. Setelah semua orang merasa nyaman dengan itu, maka pindahlah untuk menulis kasus uji sebelum kode ditulis. Kasus uji yang baik dapat melakukan banyak hal untuk mendokumentasikan perilaku suatu sistem.

Mengenai dokumen desain spesifik apa yang akan digunakan, seperti yang telah dikatakan orang lain, dokumen ini sangat tergantung pada kebutuhan tim dan apa tugas selanjutnya yang akan mereka lakukan. Jika mungkin, coba gunakan alat yang dapat menghasilkan dokumen (dari kode) yang akan Anda gunakan, atau hasilkan kode dari dokumen. Pemeliharaan dokumentasi bisa menjadi sangat mahal, jadi pilihlah dengan bijak ketika Anda mempertahankan dokumen desain.

Secara pribadi saya telah sukses dengan diagram kelas yang dihasilkan dari kode dan kasus uji kebugaran. Tim mencetak beberapa diagram kelas, melakukan sesi mark-up dengan pemilik produk dan kemudian merumuskan perkiraan dari sana. Sejauh fitnesse berjalan, saya beruntung bekerja dengan beberapa pemilik produk yang sangat pandai mengekspresikan apa yang mereka inginkan dalam spreadsheet, yang kemudian dikonversi ke tabel untuk fitnesse.

Kelas Abstrak
sumber

Desain dokumen sebagai bagian dari Agile

Jawaban: