Haruskah dokumen desain memuat diskusi tentang pro / kontra dengan desain yang diberikan atau haruskah fokus pada fakta dan alasan?

13

Saat ini saya sedang dalam proses memperbarui dokumen desain sehingga benar dan terbaru untuk pengembang masa depan.

Saat ini, dokumen hanya berfokus pada fakta-fakta, menyajikan bagaimana desainnya. Tidak ada alasan untuk setiap keputusan yang disajikan. Saya percaya bahwa penting untuk menangkap alasan agar pengembang tahu mengapa ada sesuatu seperti itu, karena itu mungkin akan mempengaruhi keputusan di masa depan. Tidak mungkin bagi saya untuk menambahkan alasan untuk semua keputusan desain, terutama yang dibuat sebelum saya mulai mengerjakan proyek, tetapi saya melakukan apa yang saya bisa di departemen ini.

Namun, beberapa keputusan desain, dengan hormat, keputusan yang sangat buruk diberikan persyaratan proyek. Ada beberapa yang bagus juga.

Pikiran awal saya adalah bahwa saya harus memasukkan diskusi tentang masalah desain dan solusi potensial atau solusi untuk masalah ini untuk memusatkan perhatian pengelola masa depan, tetapi saya tidak yakin apakah dokumen desain adalah tempat untuk jenis diskusi dan informasi ini. Saya tidak ingin "kritik" desain menjadi "mengoyak desain ini yang baru" karena orang lain mengerjakan sistem ini dan memperbarui dokumen, karena itu jelas tidak pantas.

Manajer saya akan mendukung keputusan mana pun, jadi terserah saya. Terlepas dari pendekatan yang saya ambil, dokumen yang dihasilkan akan secara resmi diversi dan diberikan kepada pengembang yang bekerja pada sistem, biasanya sebelum mereka ditugaskan untuk pekerjaan pengembangan. Diharapkan bahwa pengembang baru membiasakan diri dengan dokumen yang terkait dengan sistem perangkat lunak yang diberikan sebelum memulai pekerjaan pengembangan.

Pertanyaan:

Haruskah dokumen desain tetap berpegang pada fakta-fakta mentah ("ini desainnya") dan alasannya ("inilah alasannya desain ini") atau haruskah itu juga digunakan untuk menunjukkan masalah-masalah yang tidak cacat dengan desain yang bisa menimbulkan masalah bagi pengembang masa depan?
Jika dokumen desain tidak boleh digunakan untuk menangkap informasi ini, jenis dokumen apa yang harus menangkapnya, dan apa lagi yang harus ditangkap dengan diskusi tentang alasan-alasan desain, pengorbanan, dan masalah-masalah yang diketahui (yang tidak cacat, karena cacat dilacak) menggunakan alat lain)?

design documentation

— Thomas Owens
sumber

1

Dokumen desain bukan tempat yang tepat untuk kritik semacam itu, tetapi penting agar kekhawatiran itu disiarkan melalui beberapa cara yang tepat.

— Robert Harvey

1

@Robert Itu sepertinya jawaban bagi saya, meskipun mungkin memperluas apa yang Anda anggap berarti.

— Thomas Owens

Kesalahan, mungkin, atau Permintaan Komentar. Dokumen desain harus melalui proses revisi formal (kurang lebih). Mengizinkan orang untuk menandai dokumen semacam itu dengan kritik tampaknya bertentangan dengan proses itu, kecuali jika Anda menggunakan sesuatu seperti "komentar margin" dalam dokumen Word (mereka dapat dimatikan, menunjukkan dokumen "resmi").

— Robert Harvey

7

Jika pro dan kontra dapat diringkas dalam satu atau dua kalimat, maka tidak masalah untuk menempatkannya dalam dokumen desain. Apa pun yang lebih lama harus dipisahkan.

Di mana saya saat ini bekerja, biasanya ada dokumen "Keputusan desain" yang terpisah untuk melacak semua keputusan Besar dan Penting. Sering diformat dengan paragraf yang menjelaskan masalah (seperti "Beberapa file harus dipindahkan dari server ke pengguna tertentu di akhir setiap siklus pemrosesan, ada banyak cara untuk melakukan ini ..."), tabel dengan kolom " deskripsi solusi "(seperti" pindahkan file melalui FTP ")," pro "(seperti" Mudah bagi pengguna untuk mengelola ")," kontra "(seperti" tidak cukup aman untuk kepatuhan ABC-XYZ ") dan kesimpulan bahwa menjelaskan mengapa keputusan tertentu dipilih (seperti "FTP tidak akan digunakan karena tidak akan dapat memenuhi persyaratan kepatuhan tertentu"). Dokumen desain biasanya hanya merujuk pada keputusan yang dipilih,

— FrustratedWithFormsDesigner
sumber

Saya suka format itu dengan cukup baik. Saya mungkin harus meminjam / mencurinya untuk mencobanya, jika Anda tidak keberatan. Mungkin saya bahkan akan menyatukannya dan membagikannya di tim saya, jika itu bekerja dengan baik untuk saya dan tidak ada keberatan dari Anda.

— Thomas Owens

2

@ Thomas Owens: Lakukan! Ini bekerja dengan baik di sini, dan saya juga menyukainya. :) Saya tidak berpikir Anda bisa "mencurinya" karena saya tahu orang-orang di perusahaan lain melakukan hal serupa, itu hampir tidak "baru";)

— FrustratedWithFormsDesigner

5

Haruskah dokumen desain tetap berpegang pada fakta-fakta mentah ("ini desainnya") dan alasannya ("inilah alasannya desain ini") atau haruskah itu juga digunakan untuk menunjukkan masalah-masalah yang tidak cacat dengan desain yang bisa menimbulkan masalah bagi pengembang masa depan?

Itu bukan "salah satu atau".

Tidak ada yang membaca dokumentasi sejak awal. Mereka skim - paling banter. Karena itu, tulislah sesedikit mungkin dokumen. Satu dokumen adalah semua orang memiliki kesabaran untuk. Dokumen "non-desgin" kedua dengan "masalah lain" tidak mungkin dibaca sama sekali.

Keuntungan satu dokumen? Orang mungkin membacanya.

Kekurangan dari satu dokumen? Beberapa. Sebagian besar sudah ketinggalan zaman.

Keuntungan dari banyak dokumen? Tidak ada

Kerugian beberapa dokumen? Silakan baca prinsip KERING dan pemrograman melek. Banyak dokumen berarti banyak sumber kesalahan. Setiap dokumen tidak setuju dengan yang lain dan tidak setuju dengan kode. Ini sangat jelas. Inilah jalan kegilaan.

Hindari meremas-remas tangan.

Dokumen pro-dan-kontra dapat berlarut-larut sampai ke kedalaman yang tidak terbatas dari diskusi tentang bagaimana-jika dan gangguan yang menarik.

Jika Anda merasa perlu untuk menyajikan pro dan kontra, buatlah singkat dan to the point.

Fokus pada apa yang ada.

Simpan apa yang tidak sampai ke tulang kosong.

Jika Anda telah melakukan tolok ukur, studi, atau benar-benar menjelajahi alternatif, dokumentasikan hal itu. Tetapi jika Anda hanya mempertimbangkan alternatif, minimalkan.

Ini seharusnya tidak menjadi sejarah pribadi Anda akan pencobaan dan kesengsaraan.

Punya masalah? Memperbaikinya? Butuh berminggu-minggu? Benar-benar kesulitan? Anekdot yang menarik. Sudah diperbaiki dalam kode. Versi sebelumnya, versi yang salah, versi kereta dan versi kinerja rendah tidak masalah. Mereka adalah pencari makanan di blog.
Masih ada masalah? Tidak tetap? Itu artinya ada alternatif. Dokumentasikan ini.

— S.Lott
sumber

Dua kalimat terakhir Anda terutama benar. Semua yang saya rencanakan untuk dibahas adalah masalah yang saya hadapi dalam mengimplementasikan fitur / memperbaiki cacat, menulis tes, atau menemukan selama pembuatan profil, dan bukan hanya kritik keseluruhan terhadap desain secara keseluruhan. Apakah Anda merekomendasikan untuk mendokumentasikan ini dalam dokumen desain atau dokumen terpisah?

— Thomas Owens

"Masalah yang saya hadapi"? Intinya tidak relevan. Kode adalah solusinya, masalahnya biasanya hanya berupa komentar. "ditemukan saat profil" berarti sudah diperbaiki, jadi sudah ada di masa lalu, dan tidak memiliki relevansi sama sekali. Jangan gunakan ini sebagai latihan "penjurnalan".

— S.Lott

Beberapa masalah yang saya hadapi akan berdampak pada peningkatan / cacat di modul yang sama, seperti ketergantungan yang sebelumnya tidak didokumentasikan yang, dengan sendirinya bukan cacat (sehingga tidak dapat diajukan sebagai satu), tetapi mengubah cara Anda perlu mendekati masalah dalam modul tertentu. Ini sangat erat dengan sistem sehingga tidak dapat diubah pada saat ini dengan upaya yang wajar. Ini perlu ditangkap di suatu tempat untuk referensi. Juga, pembuatan profil adalah upaya pencarian fakta, tidak ada yang diperbaiki - mereka masih ada dan masih memenuhi persyaratan saat ini, tetapi berpotensi menjadi masalah di masa depan.

— Thomas Owens

Hanya untuk memperjelas. Contohnya adalah saya memiliki cacat A yang saya perbaiki. Namun, ketika memperbaiki A, saya menemukan beberapa masalah yang tidak didokumentasikan. Ini sekarang didokumentasikan dalam kode, tetapi perlu ditangkap di tempat lain juga. Ini biasanya di bawah level kelas dan dalam metode, sehingga hubungan ini dan masalah potensial tidak akan ditangkap pada diagram kelas atau diagram urutan. Mereka tidak dapat diperbaiki atau ditangani dengan jumlah usaha yang wajar, dan mereka tidak menyebabkan masalah fungsional atau kinerja. Bagaimana saya sebaiknya menangkap informasi ini di luar kode?

— Thomas Owens

1

@ Thomas Owens: Anggaplah Anda unik dan semua orang malas. "Aku tidak bisa membayangkan siapa pun yang tidak". Anda perlu bertemu lebih banyak orang dan melihat betapa sedikit stok yang disimpan dalam dokumentasi. Sebagai contoh. 100 pertanyaan StackOverflow - setiap hari - dijawab sepele oleh tutorial. Namun. Orang tidak membaca dan mengajukan pertanyaan konyol yang sempurna. Saya hanya bisa mengulangi apa yang telah saya amati selama 3 dekade terakhir. Orang tidak membaca. Pengalaman Anda mungkin berbeda. Anda meminta saran. Saya memberikannya kepada Anda.

— S.Lott

2

Ada 3 fakta penting dalam proses pengambilan keputusan:

Apa yang dicoba dan tidak berhasil (dan mengapa itu tidak berhasil, karena Anda menargetkan target bergerak)
apa yang
Apa yang bisa (tinggal menunggu X diimplementasikan ...)

Namun, terlepas dari "Apa itu", semua yang lain akan membingungkan pembaca dan mencegahnya dari groking sistem.

Saya suka ide menangkap 2 lainnya, meskipun mereka kurang menarik untuk mempelajari sistem, mereka bisa menghemat waktu ketika mengubahnya.

Oleh karena itu, saya akan membangun ide yang terpapar @FrustratedWithFormsDesigner, dengan twist. Alih-alih membuat dokumen lain, dengan siklus hidup sendiri, saya akan memperbaiki bagian lampiran. Kemudian untuk setiap keputusan yang layak dibahas, saya akan menunjuk pada entri yang relevan dalam lampiran.

— Matthieu M.
sumber

1

Iya. Dokumen desain harus menjelaskan manfaat, risiko, dan asumsi yang terkait dengan desain yang dijelaskan. Dokumen desain memiliki beberapa tujuan:

Dapatkan desain yang ditulis sehingga semua orang memahaminya, dan agar pemahaman setiap orang tidak melayang dari waktu ke waktu.
Komunikasikan desain kepada orang-orang non-teknis yang bekerja di proyek.
Membantu penjadwalan, alokasi sumber daya, estimasi biaya, dan jenis perencanaan lainnya.
Menjadi bagian penting dari keseluruhan dokumentasi proyek. Ketika Anda bergabung dengan proyek yang sedang berjalan, atau harus mempertahankan yang sudah selesai, hidup akan jauh lebih mudah jika ada dokumen desain yang ditulis dengan baik.
Sering kali salah satu hasil yang disyaratkan oleh kontrak.

(Mungkin ada yang lain, tapi ini awal yang baik.)

Setiap tujuan ini dilayani dengan baik oleh dokumen desain yang dengan jelas menjelaskan mengapa desain ini dipilih dan apa risiko yang terkait:

Sangat penting bagi setiap orang di tim untuk mengetahui risiko dan manfaatnya sehingga mereka dapat bekerja sama untuk menghindari risiko tersebut dan memanfaatkan manfaat desain dengan sebaik-baiknya.
Untuk anggota tim non-teknis, memahami risiko dan manfaat seringkali lebih penting daripada rincian desain itu sendiri.
Manajemen risiko adalah salah satu hal terpenting yang dapat dilakukan manajer proyek untuk memastikan keberhasilan, dan langkah pertama adalah mengidentifikasi risiko yang perlu dikelola. Seharusnya tergantung pada manajer untuk memutuskan bagaimana menghadapi risiko, tetapi tanggung jawab desainer untuk menunjukkan risiko desain yang diketahui.
Bahkan ketika risiko tidak lagi menjadi masalah, sering kali berguna untuk mendokumentasikannya karena dapat membantu menjelaskan situasi pada saat desain dibuat. Itu bisa membuat pengelola memutuskan sesuatu seperti: "Oke, mereka melakukannya dengan cara itu dulu karena ... tapi itu bukan masalah lagi, jadi saya bisa mengganti kode itu dengan implementasi yang lebih sederhana, lebih cepat." Sama halnya dengan manfaat, tentu saja.
Jika Anda mengerjakan proyek untuk klien, maka sangat penting untuk mendokumentasikan risiko dan manfaat. Yang menempatkan klien pada pemberitahuan bahwa sesuatu bisa salah dalam keadaan tertentu, atau bahwa meminta perubahan pada desain dapat membahayakan beberapa manfaat yang dijanjikan.

Saya mengumpulkan dari pertanyaan bahwa Anda bekerja dengan dokumen desain yang ada untuk sistem yang telah diterapkan. Dalam hal itu, banyak risiko yang mungkin bukan risiko lagi, jadi tidak masuk akal untuk mencoba mendokumentasikannya setelah fakta. Namun, sekarang Anda memiliki keuntungan karena Anda dapat melihat bagian-bagian dari desain asli yang tidak bekerja dengan baik. Saya pikir Anda harus: menambahkan bagian terpisah yang mengidentifikasi area masalah saat ini dan mengusulkan solusi (termasuk risiko yang terkait!); atau buat dokumen terpisah yang melakukan hal yang sama. Bagian / dokumen baru ini dapat berkembang menjadi dokumen desain untuk versi perangkat lunak berikutnya.

Inilah entri blog tentang menulis dokumen desain yang mungkin bermanfaat bagi Anda.

— Caleb
sumber

0

Jika ada alasan yang sah untuk menghindari solusi yang lebih jelas atau standar, itu harus diperhatikan. Anda akan menyelamatkan seseorang dari banyak masalah. Namun, teknologi tertentu dapat meningkat seiring waktu, jadi alasan Anda mungkin tidak berlaku. Pengembang masa depan kemudian dapat menggunakan penilaian mereka sendiri.

Saya tidak tahu apakah ada banyak manfaat untuk menunjukkan semua kekurangan. Mungkin tidak praktis untuk melakukan perubahan atau prioritas lain akan terjadi. Anda dapat memperbaiki beberapa dari mereka dalam waktu dekat dan ini hanya akan menjadi satu hal lagi untuk diperbarui.

— JeffO
sumber

Mereka belum tentu hal-hal yang dapat diperbaiki, tetapi kebanyakan adalah "gotcha" yang mungkin dilupakan banyak orang atau area yang tidak sepenuhnya jelas bagaimana mereka terkait. Namun, pendekatan yang sensitif terhadap waktu adalah ide yang bagus. Aplikasi ini berusia sekitar 5 tahun, dan mereka hanya memiliki akses ke berbagai alat dan teknologi saat itu, dan itu perlu diingat, terlepas dari pendekatan yang saya ambil,

— Thomas Owens

0

Saya pribadi tidak akan memasukkannya ke dokumen desain. Dokumen desain harus menguraikan bagaimana itu, bukan mengapa.

Jika Anda merasa ada kebutuhan yang baik untuk cerita belakang mengapa desainnya seperti itu, mungkin Anda harus memasukkannya ke dalam artikel wiki (atau basis pengetahuan apa pun yang digunakan perusahaan Anda) sehingga dapat ada sejarah evolusi desain. Orang-orang dapat pergi dan membacanya, mengeditnya, dan menambahkan saran. Dengan begitu, ini lebih merupakan diskusi terbuka alih-alih pemukulan alis dalam dokumen.

— Tyanna
sumber

Semua dokumentasi dan pengetahuan disimpan dalam dokumen Word, lembar kerja Excel, diagram Visio atau Rasional, dan presentasi PowerPoint yang diversi. Saya akan perlu menambahkan ke dokumen desain atau membuat dokumen baru dengan alat dan versi yang ada di repositori dokumen untuk proyek tersebut.

— Thomas Owens

@ Thomas Owens - Saya melihat kesulitan Anda saat itu. Saya masih tidak akan memasukkannya ke dalam dokumen utama, tetapi diskusi semacam itu bagus dan tidak hanya hidup dalam ingatan para devs asli. Mungkin menambahkannya sebagai komentar pada dokumen utama itu sendiri? Dengan begitu Anda bisa memberi wawasan tanpa terpisah dari teks utama.

— Tyanna

0

Saya setuju dengan Anda tentang menempatkan pemikiran dalam dokumen desain.

Bagaimanapun,

dalam proses memperbarui dokumen desain yang ditulis oleh orang lain, saya akan tetap rendah hati dan tidak mencoba menebak mengapa keputusan seperti itu diambil.

Begitu,

Saya akan memasukkan alasan hanya tentang perubahan yang dibuat dalam desain selama pemeliharaan.

— mouviciel
sumber

Jelas kalimat terakhir itu. Saya tidak tahu mengapa Jim, Bob, dan Steve memutuskan untuk merancang aplikasi mereka dengan cara ini, jadi saya bahkan tidak akan mencoba merasionalisasi itu. Namun, saya dapat memastikan bahwa modul atau komponen tertentu dikaitkan dengan persyaratan dan juga merasionalisasi keputusan yang saya buat.

— Thomas Owens