Dokumentasi merendahkan - bagaimana menghadapinya?

Penting : kami tidak memiliki masalah apa pun dengan dokumentasi kode sumber . Ini milik audit kode reguler dan selalu diperbarui. Masalah kami adalah dengan dokumentasi pengembang (atau, "eksternal" jika Anda mau), sedikit tips seperti blog dari programmer ke programmer yang cenderung sekali ditulis, sering tertinggal.

Kami menggunakan sistem seperti wiki untuk menghasilkan dokumentasi pemrogram - artikel yang ditulis oleh pemrogram untuk pemrogram menjelaskan sedikit lebih detail bagaimana potongan kode tertentu bekerja. Halaman-halaman wiki itu biasanya termasuk:

• motivasi di balik keputusan desain untuk bagian API (misalnya; kami melakukan hal buruk ini karena perpustakaan pihak ke-3 ini menginginkan hal-hal yang harus dilakukan dengan cara ini, karena perpustakaan lain ini ..., karena ...)
• penjelasan tentang bagaimana kami menangani tugas-tugas umum tertentu (misalnya; menampilkan sembulan sepele, yang perlu merujuk gaya aplikasi yang sesuai, mendaftarkan dirinya dalam komponen registri, dan mengimplementasikan beberapa antarmuka agar secara otomatis "dipindai" oleh komponen lain)
• praktik yang baik (subjektif seperti apa adanya, kami benar-benar menuliskannya)
• konfigurasi lingkungan, alat yang diperlukan dan pengaturannya

Secara umum, terutama hal-hal yang berkaitan dengan penulisan kode yang tidak sesuai dengan dokumentasi kode biasa karena ukuran dan sifat posting blog / artikelnya.

Masalah

Sejauh memperkenalkan sistem ini sepertinya ide yang bagus beberapa bulan yang lalu, saat ini saya merasa seperti menyebabkan lebih banyak masalah daripada menyelesaikannya. Sebagai contoh:

• orang - orang menulis artikel ... tetapi begitu kode diubah, pembaruan wiki jarang mengikuti
• banyak artikel awal , ditulis oleh seseorang yang terburu-buru dan dibiarkan begitu saja
• meskipun permintaan artikel biasanya berasal dari pimpinan proyek, hampir tidak pernah diverifikasi untuk kebenaran / komposisi - yang kadang-kadang menghasilkan kualitas yang buruk

Degradasi yang biasa. Kode berubah, wiki tetap sama. Lain kali seseorang mencari informasi, yang biasanya ia temukan adalah barang-barang usang yang berkualitas rendah - dan bertanya-tanya apa yang terjadi, apakah barang-barang yang ia temukan akurat atau (bahkan lebih buruk) bagian mana dari itu. Dan apa yang seharusnya membantu, akhirnya melakukan yang sebaliknya.

Pada saat ini tampaknya orang-orang sadar akan masalah tersebut, termasuk pimpinan proyek, tetapi tampaknya tidak ada yang merasa terganggu untuk melakukan apa pun dengannya (atau memiliki hal-hal yang lebih menarik untuk dilakukan).

Pikiran awal saya adalah membuang semuanya ke dalam pelupaan (setelah saya digigit oleh "tips" yang sudah usang beberapa kali berturut-turut), tapi saya kira itu mungkin terlalu ekstrem. Beberapa informasi perlu diperhatikan dan kadang-kadang dibaca dengan baik, tetapi masalahnya masih sama: bagaimana Anda menangani "up-to-dateness" -nya ? Memilikinya terkait dengan kode sumber entah bagaimana (jadi ketika diperbarui versi file diperiksa ke dalam, penulis artikel akan diberitahu bahwa ia mungkin perlu merevisi kode / tulisan)? Sudahkah orang yang ditunjuk "mengawasinya" dengan dasar harian? Apakah pembersihan rutin?

Sepertinya Anda terlalu banyak mendokumentasikan hal-hal sepele di wiki.

Mendokumentasikan blok kode dan metode dalam kode . Cobalah membuat kode Anda sendiri sehingga Anda tidak perlu membuat banyak komentar. Tes unit penulisan juga dapat membantu.

Dokumentasikan keputusan desain dan arsitektur pada granularity yang lebih tinggi di wiki sehingga wiki tidak perlu sering berubah atau perlu banyak pekerjaan untuk diubah. Jika banyak orang di tim Anda sudah tahu arsitektur dan tim tidak berkembang pesat maka mungkin tidak ada alasan kuat untuk mendokumentasikan mereka sama sekali, tatap muka sering kali merupakan transfer pengetahuan terbaik.

Tulis ulang atau hapus informasi yang ketinggalan zaman dengan segera , seperti kode mati semakin lama semakin sulit ditemukan dan semakin banyak akumulasi. Jika Anda tidak punya waktu cukup hapus saja dan tandai artikel itu membutuhkan pengerjaan ulang, itu memperlambat Anda dan tetap disimpan dalam kontrol versi.

Prosedur dokumen dengan mengotomatiskannya dalam skrip atau file instalasi. Kalau tidak menyimpannya di wiki, tetapi setiap kali seseorang menggunakan prosedur dari wiki, beri tahu mereka untuk mencoba memperbaiki artikel atau mengotomatiskan bagian dari proses.

Artikel blog termasuk dalam blog . Jika orang ingin berbagi pendapat dan saran pribadi mereka, buat blog perusahaan untuk itu. Mereka mungkin tidak ingin artikel mereka dimodifikasi dan tidak ada yang akan memodifikasinya, jadi jangan biarkan mereka mengacaukan wiki.

Dokumentasi harus diperlakukan sebagai hasil dan dengan demikian tunduk pada aturan keterlacakan dan penerimaan, serta diberi jumlah waktu yang sesuai untuk dikembangkan.

Bukan hal yang aneh untuk melihat orang-orang "mengharapkan" dokumentasi perangkat lunak untuk diberikan, padahal sebenarnya tidak.

Radikal tetapi efektif. Jika seseorang menulis modul baru tetapi tidak mendokumentasikannya - buka kembali tugas di pelacak masalah dan jika perlu cegah pengiriman semua kode sumber yang tidak didokumentasikan. Jika Anda mengizinkan pengembang untuk memperlakukan dokumentasi kode sumber sebagai kejahatan yang diperlukan, Anda akan berakhir dengan potongan-potongan dokumentasi yang terpisah-pisah.

Dalam proyek terbaru saya, kami cenderung untuk setidaknya melacak semua perpustakaan pihak ketiga yang diperlukan. Jika seseorang memperkenalkan perpustakaan baru, tetapi tidak didokumentasikan - kami memutar kembali solusinya hingga dokumentasi diperkenalkan. Tanpa pendekatan radikal seperti itu akan ada kekacauan. Misalnya pengembang yang tidak berpengalaman dapat menggunakan perpustakaan yang lisensinya bertentangan dengan lisensi perangkat lunak kami.

Jika ada sesuatu yang berubah dengan cepat, itu tidak harus dipertahankan di luar kode.

motivasi di balik keputusan desain untuk bagian API

Ini sangat penting untuk tetap dekat dengan kode. Seperti dalam, dalam file sumber yang sama. Dengan begitu, akan sedikit lebih sulit untuk diabaikan setiap kali seseorang menyentuh file tersebut, dan meminta lebih sedikit pengiriman ke TheDailyWTF oleh orang-orang yang tidak tahu bahwa dokumentasi eksternal ada.

Degradasi yang biasa. Kode berubah, wiki tetap sama.

Di sinilah "dokumentasi yang dapat dieksekusi" - tes unit - menjadi sangat berguna. Jika kode berubah dan tes tidak berubah seiring dengan itu, maka build akan rusak. Tentu saja, menulis tes sebagai dokumentasi membutuhkan keterampilan. Tetapi begitu juga dengan menulis dokumentasi eksternal (bagus).

Cara yang baik untuk menangani masalah, adalah menjadikannya bagian dari proses. Jika Anda memiliki kode penelusuran hingga / referensi halaman yang relevan di wiki, pengembang dapat dengan mudah mengetahui apa yang perlu diperbarui. Selain itu, buat peninjau bertanggung jawab dalam peninjauan kode untuk memastikan bahwa wiki mutakhir (berkaitan dengan pembaruan).

Cara lain untuk menambahkannya sebagai bagian dari proses - karena Anda menggunakan model gesit, bagian dari proses perencanaan untuk iterasi, bisa dengan memperbarui perubahan yang direncanakan di wiki. Wiki kemudian berfungsi sebagai sumber daya 'beginilah seharusnya sesuatu'.

Jika Anda menggunakan bahasa .net, lihat ( Sandcastle ) yang mengambil dokumentasi XML (/// dalam C #) dan mengubahnya menjadi format bantuan MSDN.

Formatnya mencakup deskripsi, komentar, dan memiliki kemampuan untuk memasukkan sampel kode, serta beberapa fitur lainnya. Anda dapat menghasilkan format .CHM, .HsX, .MSCH, dan HTML / ASP.NET. Proyek sebenarnya ditambahkan ke solusi Anda, dan dibangun di atas server build. Kami telah melakukan ini dan menyebarkan ke situs web setiap rilis, dan konsumen menyukainya karena dokumentasi tersebut relevan dengan rilis, dan terus diperbarui.

Anda juga dapat menentukan apa yang akan disertakan dalam dokumentasi. Saat ini kami memiliki 2 proyek: satu untuk konsumen eksternal yang hanya mencakup kontrak dan item yang sesuai (kelas, enum, dll.), Dan satu untuk pengembang internal yang mencakup semua yang ada di API, termasuk item yang ditandai secara pribadi dan internal.

Ini telah menjadi satu-satunya dokumentasi yang kami gunakan, karena motivasi dan kebiasaan menggunakan API dapat dimasukkan di bagian Komentar dalam dokumentasi. Prosesnya bekerja dengan baik di tempat saya bekerja.

Saya akan fokus pada dua bidang, 1) Kode. 2) Tidak ada catatan kode dan dokumen.

1) Kode.

Cobalah membuatnya sendiri sebagai dokumentasi. Di masa lalu saya menemukan bahwa sering disarankan tetapi jarang dijelaskan dengan baik, jadi ...

Alih-alih kode pseudo semacam ini:

# Routine by mdd on 7/25/2012
# processes cars for sale
a=0
col = Car.all
Collection.loop |a|
 if a.stat = 'fs' then 
   a+= a.value    
   call easo 
  endif
end

Lakukan kode yang lebih mirip ini:

accumulating_potential_sale_revenue = 0
cars_to_check = Car.all
cars_to_check.loop |one_car|
  if one_car.sell_status == 'for_sale'
    accumulating_potential_sale_revenue+= one_car.sale_price
    call email_about_special_offer(car)
  endif
end

Gunakan kontrol sumber untuk melacak info 'siapa melakukan apa ketika'.

2) Bukan kode

Gunakan format wiki dan penurunan harga untuk mempertahankan informasi ini. Jadikan itu bagian dari pekerjaan. Publikasikan, poskan, dan blogkan. Buat pertemuan standar mingguan atau bulanan untuk meninjau hal-hal lama dan baru. Jadikan mantra bahwa ketika seseorang bertanya tentang sesuatu jawabannya diberikan ... bersama dengan pemikiran "haruskah ini ada di wiki untuk kali berikutnya seseorang bertanya?"