Bagaimana saya bisa mendokumentasikan pekerjaan orang lain di masa lalu? [Tutup]

Kami berada dalam situasi yang buruk karena hanya memiliki sedikit dokumentasi tentang penyesuaian yang dilakukan oleh pekerja kami sebelumnya terhadap sistem kritis bisnis. Banyak perubahan dilakukan pada Crystal Reports, entitas basis data, dan file konfigurasi / pemrograman hak milik untuk perangkat lunak ERP kami.

Dokumentasi saat ini umumnya membaca sesuatu seperti ini:

Program ini dijalankan sebelum pembuatan faktur. Bug yang dikenal: tidak ada.

Jalankan program ini setelah menginstal perangkat lunak X.

Mengubah bidang-bidang berikut dalam laporan ini: (tanpa penjelasan tentang bagaimana atau mengapa)

Toko IT kami kecil, dan dalam hal perangkat lunak ERP, sebagian besar pekerjaan dikelompokkan pada satu orang (yaitu saya sekarang) sehingga tidak ada orang lain di sini yang tahu apa yang kami lakukan. Departemen IT dan akuntansi mengetahui sedikit demi sedikit (kadang-kadang cukup membantu) tetapi itu tidak cukup.

Masalah lain adalah departemen Akuntansi kami sepertinya berpikir kami terdokumentasi dengan baik. Memang benar bahwa kami menyimpan banyak catatan tentang apa yang salah , tetapi sangat sedikit yang menjelaskan apa (jika ada) yang dilakukan untuk memperbaiki masalah ini. Kami memiliki ratusan makalah yang menjelaskan bug, tetapi dokumen yang menjelaskan perubahan (seperti yang ditunjukkan di atas) hampir tidak berguna.

Bagaimana saya bisa mendokumentasikan perubahan masa lalu ketika saya tidak tahu apa yang telah dilakukan? Saya dapat mulai dengan mendokumentasikan apa yang telah kami ubah: File, tabel basis data, dll yang perlu kami miliki agar sistem dapat bekerja. Saya juga dapat mendokumentasikan apa yang kami lakukan ; ketika laporan dijalankan, mengapa orang disuruh menggunakan laporan / program X. Tetapi ketika salah satu hal yang disesuaikan ini memiliki masalah, saya selalu kembali ke titik awal.

Bagaimana saya bisa mendokumentasikan hal ini secara proaktif untuk saya dan orang lain?

Saya pikir ini adalah latihan yang sia-sia. Jika berhasil, berhasil, jika tidak berhasil, Anda harus memperbaikinya.

Cara terbaik untuk mendokumentasikan barang-barang lama adalah ketika Anda mengerjakannya, mendokumentasikan apa yang Anda lakukan dan menjelaskan logika bisnis (yang saya anggap tidak didokumentasikan). Ini akan sangat membantu bagi pengembang baru.

Berbicara tentang mendokumentasikan kode / barang lama, seseorang harus memilikinya. Mari kita asumsikan ini adalah manajer Anda saat ini. Dia mungkin tidak memiliki pengetahuan teknis penuh tentang hal itu tetapi akan tahu perubahan apa yang dilakukan. Dalam hal ini, itu bukan pekerjaan Anda. Mungkin manajer dapat menulis sesuatu tentang perubahan apa yang dibuat. Itu akan sangat membantu untuk disimpan sebagai sejarah. Jika masalah seperti itu muncul, Anda dapat menggali area-area itu, yang mungkin sangat membantu Anda. Tapi masuk ke kode dan mendokumentasikan perubahan itu IMO sangat berguna dan mungkin tidak mungkin.

Abaikan upaya Anda untuk mendokumentasikan perubahan .

Sebagai gantinya, mulailah mendokumentasikan apa yang saat ini bekerja, dan bagaimana caranya . Tetap perbarui dokumentasi tersebut dan saat ini saat Anda membuat perubahan di masa mendatang.

Apakah Anda memiliki kontrol sumber?

Bisakah Anda mencari tahu apa yang telah berubah dari itu?

Jika demikian, maka Anda mungkin dapat memetakannya untuk perubahan bisnis, apakah fitur baru atau perbaikan bug.

Apakah mungkin untuk menghidupkan kembali kotak surat pengembang lama? (tidak yakin apakah ini layak dengan masalah privasi atau tidak). Mungkin ada banyak informasi yang bisa diperoleh dengan menjaring lewat sana.

Hal pertama yang pertama. Di mana Anda menyimpan dokumentasi Anda? Jika belum, siapkan wiki. Saya lebih suka dokuwiki sendiri, dan bahkan ada vm prebuilt , jika Anda cenderung.

Ini memberikan beberapa fitur penting:

• Documents dapat diakses di mana saja di lan perusahaan (menginstal di komputer baru ...)
• Semua dokumen ada di satu tempat
• Semua dokumen dapat dicari
• Anda dapat berkolaborasi (kolega baru, pengguna perangkat lunak)

Sekarang, jika dokumentasi Anda dalam bentuk kertas maka saya berharap yang terbaik. Jika Anda memiliki dokumen kata, buat skrip impor .

Akhirnya, gunakan saja barangnya . Setiap kali Anda perlu menginstal sesuatu, letakkan catatan di wiki. Jika Anda menekan kasing tepi, masukkan ke wiki. Di sinilah kolaborasi dapat bersinar, karena Anda membuat orang lain melakukan pekerjaan untuk Anda.

Beralih ke dokumentasi yang lebih spesifik, jika Anda perlu bekerja dengan sumber untuk berbagai proyek, pastikan Anda memiliki lingkungan pengembangan yang tepat ! Untuk daftar hal yang harus Anda miliki:

• Kontrol versi ( git , lincah , fosil )
• Pelacakan bug ( trac , mantis , redmine , fossil )
• Membangun sistem ( autotool , scon , buildbot )
• Pengendalian proyek ( gerhana , struktur direktori yang ditentukan, plugin editor )
• Dokumentasi sumber (README, TODO, INSTALL, Sumber komentar)

Akhirnya, karena dokumentasi bisa membosankan, jadikan permainan. Beri diri Anda "poin" untuk setiap item dalam daftar periksa Anda, secara berkala memeriksa "skor" Anda. Ini cara yang baik untuk melihat apa yang telah Anda capai, dan seberapa baik. Ini juga memetakan ke mana Anda harus pergi berikutnya.

Lihatlah ini sebagai kesempatan untuk belajar banyak hal tentang cara mengatur lingkungan dev yang tepat, dan jangan takut untuk mencoba sesuatu dan melanjutkan. Temukan sesuatu yang Anda sukai dan migrasi lingkungan agar semuanya menjadi lebih baik . Pendekatan ini sebagai proyek di mana Anda ingin membangun solusi terbaik.

Edit:

Seperti komentar rig di bawah ini, hal lain yang berguna untuk dilakukan adalah membuat diagram dari kode sumber. Freecode memiliki banyak hal , dan artikel ini mencantumkan beberapa untuk bahasa populer.

Yang terbaik yang dapat Anda lakukan adalah mendokumentasikan semua yang Anda tahu dan tanyakan di sekitar perusahaan untuk mendokumentasikan apa pun yang orang lain juga ketahui. Saya menyarankan memusatkan dokumentasi dalam wiki atau sesuatu yang serupa sehingga setiap orang memiliki akses ke dokumentasi yang paling mutakhir.

Anda tidak dapat mendokumentasikan sesuatu yang tidak Anda ketahui, jadi Anda berusaha untuk belajar dan menemukan mengapa sesuatu dilakukan atau Anda membiarkannya tidak berdokumen. Inilah sebabnya mengapa perusahaan perlu lebih berhati-hati untuk mendokumentasikan hal-hal sementara yang tahu masih bekerja di sana.

Jika Anda mencoba mendokumentasikan kode apa pun yang tidak Anda mengerti, saya sarankan Anda menulis unit test untuk menguji fungsionalitasnya. Dengan cara ini Anda akan lebih memahami apa yang kode lakukan dan tes itu sendiri dapat berfungsi sebagai dokumentasi.

Semoga berhasil!

Ketika saya mencoba mendokumentasikan sesuatu yang dilakukan orang lain yang tidak lagi memiliki proyek atau perusahaan, saya selalu memulai sikap: Ini adalah kotak hitam untuk semua orang termasuk saya sampai saya perlu mengubah sesuatu atau menjelaskannya kepada orang lain.

Alasan mengapa proyek ini berada dalam bentuk dokumentasi tempat Anda menemukannya adalah karena dokumentasi dari setiap pekerjaan agak sekunder untuk membuatnya berjalan. Jadi, dokumentasikan apa yang Anda ubah dan jika Anda sudah tahu bidang apa yang ada di database dan apa yang dilakukan oleh blok kode tertentu, jika untuk kepentingan orang lain selain dari milik Anda.

Anda dapat menulis tes eksplorasi otomatis. Ini memiliki beberapa keunggulan:

• Anda belajar bagaimana sistem bekerja saat Anda menulisnya

• Mereka berfungsi sebagai dokumentasi yang dapat dieksekusi untuk nanti

• Jika Anda menjalankannya secara teratur atau bahkan terus menerus, mereka memberikan jaring keamanan yang bagus untuk mendeteksi ketika perubahan merusak sesuatu atau ketika mereka perlu diperbarui

Saya tidak tahu apakah layak untuk menulis tes semacam itu di lingkungan khusus Anda.