Bagaimana cara mendokumentasikan proyek yang sudah dikembangkan?

Saya ingin tahu opsi apa yang tersedia untuk mendokumentasikan proyek yang telah dikembangkan, karena pengembang yang bekerja tidak menulis bahkan satu halaman dokumentasi pun.

Proyek ini tidak memiliki detail lain selain banyak halaman skrip dengan fungsi yang ditulis dan dimodifikasi oleh pengembang yang mengerjakan proyek ini sejak 2 tahun terakhir. Semua yang saya miliki adalah skema database dan file proyek. Saya ingin tahu apakah ada cara untuk mengatur proyek ini dan mendokumentasikannya sehingga bisa membantu bagi pengembang yang akan mengerjakan proyek ini di masa depan.

Proyek ini dikembangkan dengan PHP dan MySQL. Fungsi-fungsinya buruk dikomentari jadi saya tidak bisa mendapatkan hasil yang baik ketika saya menjalankannya dengan oksigen.

Siapa yang akan membaca dokumentasi? Untuk apa dokumentasi itu digunakan? Ini adalah pertanyaan paling penting untuk dijawab. Sebagai contoh, dokumentasi untuk pengembang pemeliharaan akan lebih fokus pada struktur sedangkan dokumentasi untuk pengembang yang terintegrasi dengan produk akan lebih fokus pada layanan web dan struktur basis data.

Secara umum, lakukan dokumentasi sebanyak yang diperlukan dan tidak lebih. Banyak organisasi memerlukan dokumentasi karena seseorang bersikeras itu adalah praktik terbaik tetapi dokumentasi akhirnya menjadi debu.

Dengan asumsi bahwa orang benar-benar akan menggunakan dokumentasi, jangan mencoba untuk menangkap kode dan basis data ke tingkat terkecil. Pengembang akan melihat kode minutiae. Alih-alih, fokuslah pada detail yang tidak terlihat dalam kode , misalnya:

1. Kasus penggunaan produk bertemu. Ini mungkin sulit mengingat usia produk tetapi menangkap apa yang dimaksudkan dengan produk tersebut memberikan konteks penting bagi pembaca dan penguji non-teknis. Siapa pesaing di pasar (jika ada)? Apakah ada yang dikecualikan dari ruang lingkup produk?
2. Persyaratan non-fungsional yang jelas . Misalnya, apakah produk ditulis untuk menangani volume tertentu? Berapa umur data itu? Di mana caching digunakan? Bagaimana cara pengguna diautentikasi? Bagaimana cara kerja kontrol akses?
3. Sebuah diagram konteks yang menunjukkan interaksi dengan sistem lain, seperti database, sumber otentikasi, backup, monitoring dan sebagainya.
4. (Jika diketahui) Risiko dan bagaimana mereka dimitigasi bersama dengan register keputusan . Ini mungkin sulit dalam retrospeksi tetapi sering ada keputusan kritis yang mempengaruhi desain. Tangkap semua yang Anda tahu.
5. Pola desain umum atau pedoman desain . Misalnya, apakah ada cara standar untuk mengakses database? Apakah ada standar pengkodean atau penamaan?
6. Jalur kode kritis , biasanya menggunakan diagram alir atau aktivitas UML atau diagram urutan. Mungkin tidak ada dalam proyek ini tetapi ini biasanya yang diucapkan pengguna bisnis.

Bahkan jika semua informasi ini tidak tersedia, mulailah sekarang . Pengembang yang datang setelah Anda akan berterima kasih.

Tes unit otomatis yang baik atau kasus uji juga dapat menjadi dokumentasi yang bermanfaat, walaupun sulit diakses oleh orang yang kurang teknis.

Sepertinya Anda perlu melakukan perubahan budaya untuk memasukkan dokumentasi . Mulailah dari yang kecil tetapi, idealnya, proyek tidak boleh "diselesaikan" sampai setidaknya memiliki tingkat dokumentasi minimal. Ini mungkin langkah yang paling sulit karena hal-hal di atas bisa Anda kendalikan. Ini adalah sesuatu yang harus dibeli orang lain. Namun, itu juga bisa menjadi yang paling bermanfaat, terutama jika proyek berikutnya yang Anda lakukan disertai dengan dokumentasi yang baik.

Di masa lalu saya telah mengelola situasi seperti ini dengan duduk bersama berbagai pemilik produk atau pengguna listrik, melalui kasus penggunaan utama mereka dan mendokumentasikannya dengan serangkaian tes. Anda dapat menggunakan ini sebagai baseline untuk sistem ketika Anda mulai membuat perubahan di masa depan. Ini juga dapat membantu mengidentifikasi area sistem yang tidak memiliki pemilik atau kasus penggunaan dan berpotensi dihapus.

Itu semua tergantung pada ukuran sistem yang sebenarnya. Jika ini adalah sistem yang kompleks dengan banyak pemangku kepentingan yang berbeda, Anda dapat membuat diagram komponen tingkat tinggi yang merinci kemampuan apa yang ada dan di mana mereka puas. Ini bisa sangat membantu untuk mengidentifikasi masalah arsitektur dalam desain sistem.

Secara umum saya sarankan menghindari dokumentasi kuno karena akan keluar-tanggal dan akan kehilangan pengembang di masa depan. Saya selalu berusaha menghasilkan dokumentasi hidup dalam bentuk tes yang akan dipertahankan saat sistem berkembang.

Hal pertama yang pertama, siapa audiens target Anda? Pengembang masa depan atau orang bisnis lainnya? Dengan jawaban atas pertanyaan itu dalam benak:

Seperti yang orang lain katakan, deskripsi tingkat tinggi adalah hal pertama yang Anda butuhkan. Jelaskan apa yang coba dilakukan sistem dalam skema yang lebih luas. Jelaskan apa yang dijalankannya, bagaimana itu cocok dengan jaringan dan berbicara dengan sistem lain. Lalu saya akan memeriksa setiap layar, tangkapan layar dan memberikan penjelasan singkat tentang apa yang dilakukan layar, dan bagaimana ia berinteraksi dengan bagian lain dari sistem. Jika ini untuk pengembang, buatlah percakapan seperti Anda menjelaskan aplikasi kepada mereka untuk pertama kalinya. Bagaimanapun, itulah inti dari dokumen (saya berasumsi).

Pemrosesan atau logika yang rumit Saya akan menggunakan diagram keadaan, diagram aliran data atau diagram urutan. Pasti melakukan diagram entitas, kemudian desain skema DB (dua hal berbeda!). Mungkin diagram kelas dasar tetapi tetap sederhana, hanya perhatikan hal-hal utama yang menarik, devs dapat mencari tahu hal itu dengan melihat kode.

Jika Anda mengalami kesulitan untuk memulai, anggap saja ada pengembang lain di ruangan itu tepat di sebelah Anda, yang tidak tahu apa-apa tentang sistem, saya relatif tidak sabar dan hanya perlu tahu intinya. Kemudian mulailah menjelaskan, dan tuliskan apa yang Anda katakan :)

Saran sebelumnya semuanya bagus, tetapi saya juga akan mempertimbangkan untuk meneliti jika komunitas pengguna Anda telah membuat sendiri dokumentasi ad-hoc. Pertanyaan Anda tidak menentukan apakah versi 'produk' Anda (sudah ada selama dua tahun) pernah dirilis ke pengguna. Jika telah digunakan, dan tidak ada dokumentasi resmi, maka tidak ada dokumentasi yang diperlukan, atau ada dokumentasi 'tidak resmi' yang mungkin belum sempurna, tetapi juga mungkin dianggap penting oleh pengguna. Coba cari di web untuk artefak yang cenderung mewakili API kritis, forum pencarian, tanyakan pengguna-daya, dan cari situs tanya jawab. Jika memungkinkan, cobalah menulis dokumentasi yang memenuhi kebutuhan teknis atau bisnis.

Pertanyaannya adalah, apakah Anda ingin mendokumentasikannya seperti sekarang atau sebagaimana mestinya?

Apa yang saya baca dari pertanyaan Anda adalah Anda berpikir tentang dokumentasi API dan tidak begitu banyak dokumentasi pengguna dan kode mungkin tidak begitu terawat dengan baik dan samar.

Saya khawatir jika Anda mendokumentasikan sekarang, Anda akhirnya akan membuang sebagian besar pekerjaan Anda, begitu kode itu di-refactored.

Saya akan mengambil pendekatan berikut:

• membuat dokumentasi tidak perlu sebanyak mungkin dengan mematuhi praktik terbaik umum. Pilih nama kelas yang bagus, nama metode, nama variabel yang dapat Anda pahami secara intuitif
• memecah kelas monster besar dan / atau fungsi di mana masuk akal
• gunakan komentar PHPdoc - Anda dapat menggunakan alat untuk membuat dokumentasi API
• tulis tes untuk itu: Tes akan membantu Anda memahami atau menentukan apa yang harus dilakukan kode.

Sekarang, Anda masih memiliki hal-hal yang tidak terdokumentasi: ini mungkin konsep umum, arsitektur, dll. Untuk ini, saya sebenarnya akan menulis dokumentasi - tetapi hanya menulis apa yang benar-benar bermanfaat dan bermanfaat.