Bagaimana Anda menghindari dokumentasi server yang tidak sinkron dengan pengaturan yang sebenarnya?

Kami memiliki dokumentasi yang cukup bagus untuk lingkungan kami (dalam format AsciiDoc) yang baru-baru ini memungkinkan orang lain untuk membuat ulang seluruh pengaturan dari awal dalam waktu kurang dari 30 menit.
Namun, saya perhatikan bahwa setelah penyetelan awal, dengan mudah terjadi bahwa perubahan kecil dilakukan pada sistem (katakanlah: inetd menjadi tidak dapat digunakan, server IMAP saya mendengarkan port tambahan untuk koneksi ManageSieve, router baru ditambahkan ke konfigurasi exim) don segera berakhir di dokumentasi (jika ada).

Ide saya adalah untuk menghindari masalah ini dengan (sebagian?) Menghasilkan dokumentasi dari file konfigurasi dan komentar di dalamnya - salah satu cara untuk mengimplementasikan ini mungkin dengan memasukkan /etcdan /usr/local/etcke dalam beberapa sistem manajemen kode sumber (say-git) dan kemudian menjalankan skrip yang meregenerasi dokumentasi di setiap komit. Namun, saya tidak yakin apakah itu akan berlebihan dan / atau terlalu sulit untuk dilakukan dengan benar (setelah semua, saya tidak ingin salinan lengkap dari file sumber dalam dokumentasi saya melainkan hanya perbedaan).

Bagaimana orang lain menghindari bahwa dokumentasi server menjadi ketinggalan jaman - apakah ada cara yang baik untuk membuat mereka tetap sinkron secara otomatis, atau apakah Anda hanya memiliki disiplin untuk memperbarui dokumentasi saat Anda memodifikasi sistem?

Anda tidak akan pernah lepas dari beberapa dokumentasi tetapi ketika Anda mengisyaratkan ada sistem yang dapat diintegrasikan ke dalam proses perubahan Anda untuk mencakup banyak hal.

• Gunakan alat manajemen konfigurasi (seperti boneka atau koki ).
• Simpan konfigurasi Anda dengan cara yang terkendali. (seperti git atau SVN )
• Pastikan konfigurasi dapat dibaca / diakses oleh manusia (mis. Teks biasa, dapat dicari db)

Dengan cara ini, dokumentasi tingkat bawah yang biasanya kita lewatkan (atau tidak repot-repot) ditegakkan dengan menyimpan yang menyebarkan informasi dalam item konfigurasi atau kode sebagai bagian dari sistem yang membuat perubahan. Ini juga memiliki bonus tambahan dari proses menjadi lebih berulang di masa depan.

Dokumentasi eksternal masih perlu diperbarui tetapi menjadi tingkat yang sangat tinggi dengan petunjuk untuk "menyebarkan x" atau "menyebarkan y" alih-alih daftar perintah / file yang panjang. Ini juga membuat perubahan dokumentasi lebih jarang dan lebih mudah yang juga berarti akan lebih mungkin untuk dilakukan.

Juga sebelum Anda pulang brew, dengan boneka seseorang mungkin sudah menulis sesuatu untuk mengelola apa yang Anda inginkan.

Jika Anda hanya mengelola satu atau dua sistem kecil, menyiapkan sistem manajemen konfigurasi besar seperti boneka atau koki tampak seperti berlebihan. (Padahal, jika Anda berencana memiliki lebih banyak sistem di masa depan, lakukan sekarang!)

Untuk pengaturan kecil seperti ini, saya sarankan menggunakan sesuatu seperti etckeeper, sebuah program yang menempatkan /etcke dalam gitrepositori dan menyediakan beberapa fungsi yang berguna, seperti melakukan komit otomatis setiap kali Anda menginstal, meningkatkan atau menghapus paket.

Anda hanya perlu memperbarui dokumentasi Anda setiap kali Anda membuat perubahan pada sistem. AKA Change Management.

Fakta bahwa sebagian besar perusahaan menerapkan manajemen perubahan dengan cara yang konyol sehingga membuatnya lebih buruk daripada tidak ada seharusnya tidak mengurangi kegunaan konsep dasar atau mencegah Anda melakukannya dengan benar.

Saya biasa menggunakan htmlatau semacam wiki untuk melacak semua konfigurasi saya. Sekarang saya bekerja di toko Windows dengan ( shudder ) SharePoint, jadi sekarang saya menggunakan dokumen Word "templates" yang saya buat untuk melacak setiap sistem yang saya miliki dan setiap perubahan konfigurasi yang saya buat, yang tidak seburuk kedengarannya, mengingat bahwa banyak sistem hanyalah salinan pemotong-cookie dari yang lain yang semuanya dapat disatukan menjadi dokumen yang sama. (Dan saya menyimpan salinan lokal dari semua barang saya untuk mendokumentasikan hard drive saya, sebenarnya diatur dengan cara yang masuk akal, selain melemparkannya ke tumpukan yang tidak terorganisir yang merupakan situs SharePoint siapa pun.)

Tantangan terbesar adalah membuat waktu untuk mendokumentasikan, yang saya lakukan dengan menambahkan waktu dokumentasi sebagai bagian dari waktu untuk melakukan perubahan. Jadi, tidak terlalu sulit, terutama jika Anda sedikit sok dan tidak keberatan menyuruh orang untuk pergi dan mengantri karena Anda terlalu sibuk untuk masalah mereka saat ini.