Menentukan jumlah dokumentasi yang tepat

Di mana saya saat ini bekerja, pendekatan umumnya adalah -

hindari dokumentasi sebanyak mungkin

Hanya mendokumentasikan jika tim lain akan membutuhkannya

hanya untuk klarifikasi, maksud saya bukan kode-dokumentasi - ini yang kami lakukan, maksud saya semua dokumentasi seputar proses desain - jika itu UML atau DB Schemas, diagram kelas dan dokumen kata dengan spesifikasi dan sejenisnya.

Saya akan mencantumkan alasan Bos saya untuk tidak mendokumentasikan:

1. itu memakan waktu - fokus pada implementasi
2. jika desain berubah - maka dokumentasi harus berubah, gandakan masalah
3. pada akhirnya Anda hanya mendapatkan ratusan halaman yang tidak seorang pun ingin membaca, dan tidak ada yang benar-benar mengedit sehingga pada saat itu akan keluar dari tanggal
4. Ini menyakitkan - tidak ada yang benar-benar ingin melakukannya

Sekarang saya menyadari bahwa kami bekerja lebih cepat, tetapi saya juga ingat waktu sampai di sini dan langsung menyelam ke beberapa kode lama, tidak mengerti apa-apa.

Sebenarnya, saya masih tidak mendapatkan sebagian besar kode lama ini, dan kadang-kadang ketika saya masuk saya melihat banyak tambalan dari pengembang yang berbeda mencoba untuk membuat tweak kecil.

Saya benar-benar berpikir kurangnya dokumentasi mempromosikan tambalan semacam ini dan kurangnya pemahaman sistem dalam arti luas.

pertanyaanku adalah:

Bagaimana kita bisa menyeimbangkan dokumentasi sehingga kita akan mempromosikan pengetahuan berkelanjutan di antara tim dan tetap cepat dan efisien?

Saya telah menemukan dokumentasi APA SAJA lebih baik daripada NO dokumentasi. Jumlah yang tepat biasanya ditentukan oleh jumlah waktu yang harus kita lakukan, atau seberapa besar kita membenci panggilan telepon dan email dukungan.

Tampaknya anggota tim Anda saat ini memiliki harapan yang tidak realistis dari ingatan mereka, atau mereka malu akan keterampilan menulis mereka, dan tidak mau berlatih.

Saya menyadari bahwa saya adalah minoritas (jurusan bahasa Inggris yang masuk ke rekayasa perangkat lunak di sekolah pascasarjana) di sini, karena saya tidak menemukan dokumentasi sebagai tugas. Ini alat profesional yang berharga. Saya mungkin merasa menulis tidak sesulit yang dilakukan oleh beberapa rekan kerja saya, tetapi itu karena saya lebih banyak berlatih. Saya tidak menganggap proyek selesai kecuali memiliki dokumentasi, dan saya biasanya menulisnya semata-mata untuk alasan egois: jadi saya dapat memberi orang sesuatu untuk dibaca daripada menerima panggilan telepon dan email, atau agar saya dapat mengingat apa yang kami bicarakan terakhir bulan, atau lebih saya bisa merujuk pada bagaimana saya melakukan sesuatu jika saya perlu mendukungnya di tengah malam.

Cara terbaik untuk mendekati dokumentasi adalah dengan menuliskannya SEPERTI ANDA PERGI, persis seperti menulis kode tes. Sungguh menakjubkan bagaimana beberapa templat pra-tertulis (dengan tajuk, potongan kode, dll.) Dapat membuat dokumentasi lebih mudah dan lebih cepat untuk dilakukan. Dengan cara ini Anda dapat menangkap perubahan saat itu terjadi, dan Anda memiliki sedikit alasan untuk dibahas seiring waktu. Anda lebih efisien dengan cara ini, karena Anda dapat merujuk ke dokumentasi sesuai kebutuhan, dan mengubahnya sepanjang jalan. Melakukannya di wiki, misalnya, membuat pembaruan lebih mudah, dan Anda dapat menghindari masalah versi dokumen jika yang terbaru dan terhebat selalu online di tempat yang sama, dan Anda bisa mengirim tautan ke orang yang perlu membacanya.

Jika Anda menghabiskan sedikit waktu untuk mendokumentasikan, Anda SEMUA akan bekerja lebih cepat, terutama ketika seseorang yang baru bergabung dengan tim, karena mereka tidak harus menghabiskan seluruh waktu itu untuk mencari tahu semuanya. Mencari tahu adalah bagian yang menyenangkan dari pekerjaan kami, tetapi itu tidak menyenangkan ketika Anda harus terburu-buru untuk memperbaiki produksi. Kita semua akan menghemat banyak waktu jika kita semua menulis beberapa catatan lagi.

Apakah tim Anda memiliki masalah yang sama dengan pengujian, atau penulisan kode pengujian? Jika tidak, ini akan menjadi penjualan yang lebih mudah.

Dokumentasi Anda bermanfaat dalam banyak hal:
1) Untuk Anda, saat ini, dan untuk rekan kerja Anda, saat Anda mengerjakan proyek.

2) Untuk pelanggan Anda. Memiliki dokumentasi (termasuk diagram) yang dapat Anda tampilkan kepada pengguna membuat diskusi dalam rapat menjadi lebih mudah, terutama jika Anda mendiskusikan sistem yang rumit. Bahkan jika dokumentasinya tidak lengkap, ini adalah tempat untuk memulai.

3) Kepada orang-orang yang akan mewarisi pekerjaan Anda (yang mungkin bahkan Anda, dalam tiga tahun). Banyak rekan kerja saya yang lebih muda berpikir mereka akan mengingat hal-hal selamanya. Saya tahu saya tidak akan mengingatnya minggu ini jika saya tidak menuliskannya. Memiliki dokumentasi membuat Anda tidak perlu menghabiskan setengah hari untuk mengingat bagaimana Anda menyusun sesuatu, dan harus memikirkannya lagi.

4) Untuk Anda dan orang lain, jika situasinya menjadi politis atau kontroversial. Sebagai seseorang yang membuat catatan dalam rapat, untuk membuat saya tetap terjaga dan melawan kebosanan, saya sering menjadi satu-satunya yang memiliki versi tertulis dari suatu keputusan. Orang yang menuliskannya memenangkan perselisihan. Ingat ini lain kali ketika seseorang berkata, "Ingat pertemuan yang kita lakukan pada musim dingin yang lalu di ruang konferensi 4, ketika kita membahas X? Fred ada di sana, dan siapa pria dari Akuntansi itu?"

Di beberapa perusahaan terakhir saya, kami memiliki wiki "pengembangan". Potongan fungsi yang signifikan (impor / ekspor umpan baru, cara kerja subsistem keamanan, di mana sistem menyimpan dokumen yang diunggah, dll.) Semuanya didokumentasikan di sana. Biasanya item wajib diisi sebelum langkah peninjauan kode. Biasanya ada sedikit penolakan di awal, tetapi begitu seseorang perlu mencari sedikit informasi dan ada di sana, Anda memiliki orang yang insaf.

Hal yang menyenangkan tentang memilikinya dalam format wiki adalah Anda tidak terlalu suka melakukan semua pemformatan Word yang cantik dan semacamnya dan hanya menuliskan informasi nyata yang perlu Anda simpan. Sebagian besar (jika tidak semua) paket wiki akan memungkinkan Anda untuk mengunggah dokumen atau gambar (seperti diagram Visio UML, atau gambar rangka UI), sehingga Anda dapat memiliki karya visual juga.

Seperti kebanyakan hal, saya pikir Anda harus bertujuan untuk melakukan jumlah minimum yang mungkin bisa berhasil. Tapi itu tidak sama dengan tidak ada.

Anda tidak dapat luput mengalokasikan waktu untuk menulis dokumentasi yang tepat. Seimbangkan itu sesuai keinginan Anda, tergantung pada seberapa banyak pekerjaan yang diberikan kepada Anda, tetapi sisakan 15-20% dari waktu Anda untuk mendokumentasikan apa yang telah Anda lakukan. Semua orang di tim harus menyetujui ini, termasuk manajer Anda, jika tidak, Anda hanya akan mendokumentasikan untuk kepentingan orang lain dan tidak akan mendapat imbalan apa pun. Dokumentasi harus menjadi bagian integral dari proses pengembangan Anda.

Dokumentasi harus memberi tahu Anda MENGAPA Anda melakukan sesuatu ketika Anda meninggalkan bagian BAGAIMANA dengan kode aktual dan bagian APA ke unit test. Ada lagi yang menyusahkan. Ini biasanya cukup baik untuk orang pintar yang hanya ingin titik awal.

Juga, jangan lupa untuk mempertahankan arsitektur tingkat tinggi secara keseluruhan dari setiap komponen besar basis kode Anda. Sangat mudah untuk melantik anggota tim baru.

Akhirnya, setiap kali Anda menambahkan perbaikan aneh, tautan ke basis data bug Anda dari komentar - sangat berguna.

Bos Anda benar, jangan cetak dokumentasi UML yang tidak akan dibaca siapa pun. Apa yang kami lakukan di tim kami adalah menavigasi langsung dalam model menggunakan tampilan diagram kelas. Prinsipnya adalah untuk selalu memperbarui MOF, model UML hidup dari kode dan membiarkan diagram kelas hanya menjadi penampil model tetapi bukan model itu sendiri.

Ini bekerja sangat baik karena semua kompleksitas dilakukan di backoffice pada level model. Saya dapat memperbaiki proyek saya, menulis java doc atau menulis dokumentasi uml dalam model. Ini adalah semacam klik dan buka. Ketika Anda mengklik Anda mendapatkan dokumentasi langsung. Jika ada sesuatu yang tidak jelas maka saya membuka diagram kelas dan mulai bermain dengannya. Hapus dari diagram pengklasifikasi, tambahkan pengklasifikasi baru, perbesar dan perkecil, tunjukkan asosiasi, hapus asosiasi dll. Model tidak berubah karena saya tidak membuat informasi model baru, saya hanya menggunakannya.

Sangat penting untuk membuka diagram paket dan dapat membaca langsung di diagram kelas komentar tentang apa yang seharusnya kelas ini. Apa metode ini seharusnya dilakukan dan apa aliran dll ...

UML hebat, sangat membantu tetapi kita harus berhenti menggunakan Model Driven Devleopment untuk memberikan lebih banyak fleksibilitas dan lebih banyak iterasi pada tahap pemodelan / pengembangan. Diagram kelas diperbarui langsung dari kode dan dokumentasi selalu akurat dan tersedia hanya dengan satu klik. Saya tidak akan menyebutkan alat tetapi jika Anda menggunakan Java dan Eclipse mudah untuk menemukan alat yang saya gunakan :-)