Apa yang harus Anda tinggalkan untuk penerus Anda?

Asumsikan bahwa Anda adalah satu-satunya pengembang yang meninggalkan pekerjaan. Informasi / materi apa, di luar kode itu sendiri, yang harus Anda buat dan tinggalkan untuk pengganti Anda?

Jawaban yang jelas adalah "apa pun yang Anda inginkan di pekerjaan baru" pasti, tetapi sudah lama sejak saya memulai pekerjaan baru, dan saya lupa apa hal terpenting yang saya butuhkan saat itu.

Saya berpikir:

• akun / kata sandi
• lokasi peralatan, cadangan, CD perangkat lunak

Apa lagi?

• Akun & Kata Sandi
• Informasi server
• Kode yang baik
• Dokumentasi
  • Diagram & penjelasan database luar biasa
  • Daftar keanehan dalam kode
• Prosedur
• Penjelasan proses manual, atau sesekali, tidak jelas, bekerja
• Daftar program yang mereka gunakan atau temukan bermanfaat
• Kontak informasi ;)

Secangkir kopi yang kuat dan catatan permintaan maaf.

Aku berharap aku ditinggalkan.

• Dokumentasi. Seberapa sulit untuk menulis beberapa komentar? Membuat catatan, menyebarkan catatan, memindahkan catatan sistem. Apa yang harus dilakukan ketika Anda me-restart dan semuanya hilang.
• Dokumen. Tulis mengapa itu dilakukan dengan cara ini, jadi saya tidak perlu bertanya-tanya mengapa Anda tidak melakukannya dengan cara lain. Bagaimana cara kerja sistem cadangan, bagaimana server merespons beban, pengujian, uji kasus, kasus penggunaan.
• Catatan. "Saat menggunakan database, jangan pernah katakan SELECT * FROM clients. Kami tidak yakin mengapa tetapi ini membuang database" .

Alamat email saya, atau bahkan nomor telepon.

Dalam pengalaman saya, sulit untuk membuat setiap detail ditulis, jadi hal terbaik adalah tersedia (sampai tingkat tertentu) jika penerus Anda membutuhkan informasi lebih lanjut.

Dokumentasi program yang Anda tulis misalnya tujuannya, lokasi file sumber untuk pengembangan di masa depan, kata sandi, dll.

Ini bisa dalam kode sebagai komentar atau di luar di depan mata.

Lebih dari sekadar dokumentasi, saya ingin tahu mengapa keputusan tertentu dibuat ketika mereka dibuat. Kami menggunakan SWIG saat ini pada proyek dan salah satu pengembang lain ingin tahu mengapa kami tidak menggunakan Boost :: Python. Jawaban sederhananya adalah bahwa pelanggan tidak mengizinkan penggunaan Boost pada saat itu. Sekarang adalah cerita yang berbeda.

Hal-hal seperti itu akan membantu mereka tidak hanya dalam memahami proyek tetapi juga keterbatasan / kendala / tantangan apa yang Anda atasi teratasi. Ini akan memberi mereka titik awal untuk pemeliharaan dan penambahan fitur di masa mendatang.

Satu hal yang saya tidak melihat orang lain menyebutkan (walaupun saya mungkin telah mengabaikannya) adalah mendokumentasikan cara mengatur lingkungan dev. Saya menyadari bahwa sebagian besar waktu hanya menginstal beberapa hal, dapatkan yang terbaru, kompilasi dan Anda selesai. Namun terkadang ada yang lebih dari itu (SharePoint adalah satu situasi yang muncul di pikiran) dan mendokumentasikan apa yang harus dikonfigurasi oleh kapasitor fluks dengan cara apa yang akan sangat membantu bagi jiwa miskin yang mengikuti Anda.

Jika ini adalah program desktop, bagaimana membangun seluruh sistem dari awal (mungkin beberapa program terpisah), cara membuat paket untuk distribusi (apa dependensi yang dimilikinya, misalnya versi .NET), dan bagaimana cara menyebarkannya ke server untuk diunduh jika itu berlaku, atau bakar ke CD atau DVD.

Jika itu adalah program berbasis web, FTP dan (jika ada) akses SSH ke server, dan alat apa yang digunakan untuk membuat dan menguji kode secara lokal.

Jika ini adalah sistem tertanam, lengkapi instruksi untuk membangun citra biner, alat apa yang digunakan, cara mengunduh dan mem-flash kode ke dalam produk, cara mengatur sistem file pada perangkat, jika ada.

Saya baru-baru ini meninggalkan pekerjaan dalam keadaan yang sama dengan Anda (saya bukan satu - satunya pengembang, tetapi hanya ada kami berdua, jadi saya memiliki cukup banyak pengetahuan yang tidak dimiliki orang lain (dan sebaliknya, tentu saja)).

Dalam hal hal-hal dokumentasi normal, penting untuk mendokumentasikan tinjauan umum dari keseluruhan sistem. Komponen individu sudah didokumentasikan dalam kode, tetapi interaksi antara komponen dan mengapa ini melakukan itu atau mengapa ini perlu berbicara dengan komponen itu penting dan tidak selalu mudah untuk mencari tahu hanya dengan men-debug / melihat kode.

Kemudian, sekitar sebulan sebelum saya pergi, setiap kali saya melakukan sesuatu yang hanya bisa saya lakukan, saya menuliskan apa yang terjadi, apa yang harus saya lakukan, dan mengapa. Ini biasanya merupakan kasus "ada bug dalam komponen xyz, untuk memperbaikinya saya tahu untuk mencari di file abc karena X, maka saya harus melakukan ini, ini dan ini".

Tentu saja, saya meninggalkan alamat email dan nomor telepon saya kalau-kalau ada sesuatu yang mereka tidak bisa mencari tahu sendiri. Saya mendapat beberapa panggilan telepon dalam beberapa minggu pertama, tetapi mereka perlahan-lahan turun.

Kita semua ingin diagram alir data lengkap dari sistem dengan daftar persyaratan fungsional. Kemungkinan besar Anda tidak pernah mendapatkannya ketika Anda menulis sistem di tempat pertama! Seperti kebanyakan tempat, dokumentasi terbaik mungkin adalah kode itu sendiri sehingga apa yang paling saya sukai adalah kode yang terdokumentasi dengan baik. Baris dan baris komentar dalam kode menjelaskan apa yang Anda coba lakukan baik secara teknis maupun fungsional.

The # 1 aturan untuk dokumentasi tidak apa yang dilakukannya, tapi mengapa . Apa latar belakang program yang dijalankan, dan apa yang mereka lakukan?

Saya pikir apa yang ingin saya lihat di dokumentasi selain yang biasa adalah fitur yang ditinggalkan. Seperti mengapa ide-ide tertentu TIDAK diimplementasikan atau platform atau metode tertentu TIDAK digunakan (yang merupakan pilihan yang jelas).

Ini memastikan bahwa penerusnya selalu tahu apa yang tidak boleh dilakukan atau jika dia lebih mampu maka mungkin dia bisa datang dengan bekerja di sekitar dan membuat fitur-fitur tertentu berfungsi.

Ini terutama berlaku untuk proyek sumber terbuka. Dapat menghemat banyak waktu dan kekuatan otak!