Dokumentasikan semuanya.
Ada utas tentang Slashdot baru-baru ini tentang memulai dokumentasi, yang mengilhami saya untuk menuliskan pemikiran saya tentang dokumentasi.
Poin kunci saya adalah:
Prinsip # 1: Tidak Pernah Dilakukan
Dokumentasi adalah upaya berkelanjutan yang akan selalu ketinggalan dari apa yang ada dalam produksi. Perubahan dilakukan secara ad-hoc, hal-hal yang bergerak di sekitar atau dihentikan atau dioperasikan secara acak. Dokumentasi tidak akan pernah ketinggalan.
Anda harus menjual orang-orang yang membayar tagihan berdasarkan nilai waktu yang dihabiskan (dan karenanya, uang) untuk menjaga agar dokumentasi yang berjalan tetap mutakhir. Sering kali percakapan itu seperti ini: "ingat ketika saya harus menghabiskan $ WAKTU mencari tahu bagaimana $ HAL rusak? Nah ketika saya selesai, ada catatan teknologi ini merinci $ HAL, sehingga orang berikutnya yang datang tidak akan harus memikirkan semuanya. "
Anda harus melakukannya, meskipun Anda tidak akan pernah selesai.
Prinsip # 2: Satu-satunya Hal yang Lebih Buruk daripada Tidak Ada Dokumentasi Adalah Dokumentasi yang Salah
Ini lebih disangkal daripada sebuah prinsip. Dokumentasi dapat membuai Anda ke perasaan salah bahwa ada sesuatu yang diketahui dan jika ada yang salah, Anda dapat menjalankannya untuk memperbaikinya.
Penting untuk mengakui masalah ini.
Prinsip # 3: Anda Menulis Dokumentasi Untuk Pengganti Anda
Peluangnya adalah 95% dari apa pun yang Anda dokumentasikan, Anda tidak perlu merujuk lagi. Dokumentasi adalah kumpulan kebijaksanaan untuk masa depan, bukan untuk Anda. Jadi, Anda harus berasumsi bahwa audiens Anda tahu sedikit atau tidak sama sekali tentang hal-hal spesifik tentang bagaimana keadaan mereka.
Dan akan ada penerusnya. Saya tidak tahu tentang Anda, tetapi saya tidak berencana untuk berada di lingkungan khusus ini selama sisa hidup saya. Peluang datang dan pergi, dan ketika mereka datang, kadang-kadang Anda pergi. Tetapi hidup terus berjalan di belakang Anda, dan semakin halus Anda dapat menjadikan hidup bagi penerus Anda semakin baik. Kalau tidak, Anda mungkin memiliki koleksi mantan pelanggan yang diam-diam mengatakan hal-hal yang tidak menyenangkan tentang Anda. Saya suka mengatakan bahwa itu adalah 50 orang yang sama yang bekerja di mana-mana di TI di Ottawa karena Anda terus bertemu mereka di mana-mana. Membantu penerus Anda mungkin membuka pintu bagi Anda di masa depan.
Sekarang sampai batas tertentu selalu ada tingkat "menyalahkan pria sebelumnya" ketika masalah muncul. Itu adalah bagian dari bisnis. Saya sudah melakukannya sendiri. Tetapi pada beberapa kesempatan ketika saya mengecam lelaki sebelumnya sebagai semacam orang tolol, saya telah belajar sebaliknya bahwa dia benar-benar telah bertindak bersama dan tahu lebih banyak tentang apa yang sedang terjadi daripada yang saya lakukan pada saat itu.
Prinsip # 4: "Mengapa" seringkali lebih penting daripada "Bagaimana"
Ketika melihat suatu sistem, kebanyakan dari kita mulai berpikir berpikir mengapa ini seperti ini? Hampir selalu ada alasan khusus untuk pilihan konfigurasi yang dibuat. Dalam keadaan ini, "Mengapa" menentukan "Bagaimana", dan Anda harus memastikan bahwa pembaca memahami masalah spesifik yang dipecahkan ketika memeriksa sisa-sisa merokok dari solusi Anda.
Prinsip # 5: Itu harus mudah atau Anda tidak akan melakukannya
Ini berarti Anda harus sangat menyadari alat Anda serta mereka yang akan menggunakan alat Anda.
Menjaga hal-hal terbaru harus mudah. Jika Anda harus melakukan upaya apa pun, maka Anda akan menemukan alasan untuk tidak melakukannya saat itu dilakukan, yang segera setelah perubahan.
Jika alat Anda tidak mudah digunakan orang lain, maka mereka tidak akan menggunakannya. Ini bisa sangat melumpuhkan dalam lingkungan tim, karena semakin besar tim semakin besar kemungkinan Anda akan bertemu dengan anggota tim yang tidak menyukai alat pilihan Anda.
Secara pribadi, saya suka wiki untuk dokumen. Namun masalahnya adalah bahwa wiki tidak memaksa struktur pada Anda, jadi struktur itu harus dipaksakan dari luar. Ini selalu mengarah pada konflik di suatu tempat karena orang lain memiliki ide yang lebih baik / berbeda.
Di beberapa tempat saya telah menggunakan dokumen Word dan Visio "diterbitkan" ke PDF, dengan PDF "terbaru" dianggap otoritatif. Ini bagus karena Anda kemudian memiliki koleksi yang dapat Anda serahkan kepada majikan / penerus Anda. PDF, jika diberi tanggal yang tepat, dapat memberikan catatan sejarah tentang apa yang terjadi, meskipun yang tidak mudah dinavigasi. Itu buruk karena saya tidak suka Word atau Visio dan telah dipaksa untuk mendapatkan pemahaman dasar tentang alat-alat ini untuk mengkomunikasikan ide-ide secara efektif.
Majikan saya saat ini sedang mempermainkan ide dokumen Word di portal Sharepoint. Kita hanya harus melihat seberapa jauh kita sampai di sana