Dokumentasi sistem punya reputasi buruk. Sebagian besar dibuat di minggu terakhir proyek, ditulis agar bisa dicentang di daftar serah terima, lalu tidak pernah dibuka lagi. Ketika benar-benar dibutuhkan, isinya sudah tidak cocok dengan kenyataan.
Cara yang kami temukan paling membantu untuk memperbaikinya sederhana: bayangkan Anda sedang menulis surat untuk satu orang. Orang itu pintar, tetapi tidak ikut proyek ini, dan baru tiba hari Senin pukul sembilan untuk menggantikan Anda.
Apa yang ditanyakan orang itu di hari pertama
Kalau kita memikirkan penggantinya, daftar isinya menyusun diri sendiri. Dia akan bertanya:
- Sistem ini sebenarnya untuk apa dan siapa yang memakainya? Dua paragraf, tanpa istilah teknis. Tanpa ini, setiap keputusan perubahan berikutnya diambil tanpa konteks.
- Bagaimana cara menjalankannya di komputer saya? Langkah persis dari nol, termasuk versi perangkat lunak yang dipakai. Cobalah mengikuti langkah itu sendiri di komputer yang bersih. Hampir selalu ada satu langkah yang ternyata tertinggal.
- Di mana letak server, domain, dan akun-akunnya, dan siapa pemiliknya? Bukan passwordnya di dokumen ini, tetapi di mana password disimpan dan siapa yang bisa memberikan akses.
- Apa yang sering rusak dan bagaimana biasanya diperbaiki? Ini bagian yang paling jarang ditulis dan paling berharga. "Kalau laporan bulanan kosong, biasanya tugas terjadwal berhenti, jalankan ulang dengan perintah ini."
- Kenapa dibuat begini, bukan begitu? Keputusan yang janggal di kode sering ada alasannya: aturan dari instansi, keterbatasan server, permintaan khusus klien. Satu kalimat alasan menyelamatkan orang berikutnya dari mengubah sesuatu yang sebenarnya sengaja.
Yang tidak perlu ditulis
Dokumentasi sering gemuk oleh hal yang bisa dibaca langsung dari kode, seperti daftar semua fungsi beserta parameternya. Informasi itu cepat usang dan selalu bisa dilihat di sumbernya. Gunakan halaman Anda untuk hal yang tidak ada di kode: konteks, alasan, dan kebiasaan operasional.
Tempat menyimpannya
Taruh dokumen di dekat kode atau dekat sistemnya, bukan di folder pribadi seseorang. Berkas teks sederhana di repositori yang sama dengan aplikasi sudah cukup. Dengan begitu, siapa pun yang mengubah sistem melihat dokumennya saat itu juga, dan perubahan dokumen ikut tercatat bersama perubahan kode.
Ujinya
Minta seseorang yang tidak terlibat proyek menjalankan sistem hanya dengan membaca dokumen itu, dan Anda tidak boleh membantu. Setiap kali dia bertanya, itu satu celah yang harus ditutup. Dua jam uji seperti ini biasanya lebih berguna daripada dua hari menulis tambahan.
Kalau Anda adalah pihak yang memesan sistem dari vendor, jadikan ini syarat serah terima yang konkret: bukan "dokumentasi lengkap", tetapi "orang kami bisa menjalankan dan memperbaiki masalah umum hanya dengan dokumen ini".