As-A-Manual Dokumentasi vs. Dokumentasi As-A-Checklist

Saya pernah berdiskusi dengan orang lain di departemen saya tentang dokumentasi, khususnya, tingkat detail dan persyaratan. Dalam pandangan mereka, dokumentasi adalah daftar periksa sederhana dari hal-hal yang harus dilakukan ketika hal X salah.

Saya tidak setuju. Saya pikir ini mengandaikan bahwa semua masalah di TI dapat dengan mudah diringkas ke daftar sederhana prosedur pemulihan. Saya pikir itu benar-benar mengabaikan kompleksitas situasi, dan karena orang lain di departemen tidak selalu memiliki pemahaman yang mendalam tentang masalah ini (itulah sebabnya saya menulis dokumen - sehingga mereka memiliki sesuatu untuk dijadikan referensi ) bahwa dokumentasi harus mencakup beberapa bahan latar belakang dasar, seperti:

• Tujuan dari (sub) sistem yang dimaksud
• Mengapa itu dikonfigurasi dengan cara itu
• Ekspektasi peristiwa akan terjadi ketika pengaturan / prosedur dilaksanakan
• Masalah potensial yang dapat menyebabkan prosedur gagal

Namun, aku lebih suka kalah suara ini, jadi dokumentasi saya diperlukan untuk menjadi ditulis ulang ke dalam bentuk yang mengatakan "Langkah-langkah ABC diterapkan dalam rangka akan menyelesaikan masalah X". Saya sering mendengar ratapan bahwa itu harus sesuai dengan satu halaman kertas. Coba jelaskan konfigurasi Squid ACL kepada seseorang dengan cara ini, termasuk pemecahan masalah, melalui dokumen satu halaman. Itu hanya satu dari setengah lusin dokumen yang "menunggu untuk ditulis" sebagai daftar periksa pemulihan.

Apakah metode yang saya anjurkan benar-benar berlebihan? Atau apakah mereka benar, dan saya hanya harus mengurus bisnis saya di sini dan hanya menuliskannya daftar periksa sederhana? Kekhawatiran saya adalah, tidak peduli seberapa baik Anda menulis daftar prosedur, itu benar-benar tidak menyelesaikan masalah yang mengharuskan SysAdmin untuk memikirkan semuanya. Jika Anda menghabiskan waktu melakukan daftar periksa prosedur pemulihan yang akhirnya tidak menyelesaikan masalah (karena ada faktor tambahan yang bukan merupakan bagian dari dokumen, karena fokus dokumen yang sempit ), dan tujuan dari dokumen adalah untuk menghindari membaca kembali halaman manual dan wiki dan situs web lagi, lalu mengapa saya melalui gerakan? Apakah saya terlalu khawatir, atau ini masalah nyata?

EDIT:

Saat ini tidak ada posisi helpdesk di departemen. Audiensi untuk dokumentasi akan untuk admin lain atau untuk kepala departemen.

Saat menulis milik saya, saya selalu beralih ke menulis dua tiga set. Daftar periksa penyelesaian, dengan lampiran JAUH LEBIH LAMA tentang arsitektur sistem termasuk mengapa hal-hal dilakukan sebagaimana mestinya, kemungkinan titik lengket ketika datang online, dan asumsi desain abstrak. diikuti oleh daftar kemungkinan masalah dan resolusi mereka, diikuti oleh bagian yang lebih panjang dengan informasi tentang cara kerja sistem, mengapa ia melakukannya seperti itu, dan informasi lain yang berguna untuk mengarahkan orang ke arah yang benar jika sesuatu yang unik terjadi.

Pada pekerjaan terakhir saya, kami diminta untuk menulis dokumen sehingga bahkan helpdesk level-1 orang dapat membawa hal-hal kembali. Ini memerlukan daftar periksa, yang umumnya menjadi usang dalam waktu 3 bulan setelah penulisan. Kami sangat terdorong untuk menulis panduan pemecahan masalah bila memungkinkan, tetapi ketika pohon darurat mendapat lebih dari tiga cabang di dalamnya, Anda tidak dapat menulis dokumen itu tanpa abstrak.

Ketika meninggalkan pekerjaan terakhir saya, saya membuka manual 100 halaman 'bagaimana melakukan pekerjaan saya' sebelum saya pergi. Ada hal-hal abstrak di dalamnya, filosofi desain, serta poin integrasi. Karena saya mungkin menulis untuk sysadmin lain yang akan menggantikan saya, saya mengarahkannya pada seseorang yang dapat mengambil gagasan abstrak dan mengubahnya menjadi tindakan nyata.

Lima tahun telah berlalu dan saya menemukan pendapat saya tentang ini agak berubah. Baik Dokumen sebagai Manual dan Dokumen sebagai Daftar Periksa memiliki tempat yang sangat berharga dalam hierarki dokumentasi dan keduanya harus diproduksi. Mereka menargetkan audiens yang sangat berbeda.

Dokumentasikan sebagai Daftar Periksa

Target pasar untuk dokumentasi semacam ini adalah rekan kerja yang ingin bagaimana cara melakukan sesuatu. Mereka datang dalam dua jenis:

• Rekan kerja yang hanya ingin tahu cara melakukan sesuatu dan tidak punya waktu untuk membaca manual lima belas halaman dan mencari tahu langkah-langkahnya sendiri.
• Prosedur yang cukup rumit dalam langkah-langkah, tetapi hanya perlu dijalankan sesekali.

Ketidaksabaran adalah pendorong untuk jenis pertama. Mungkin rekan kerja Anda tidak benar-benar ingin tahu mengapa output harus disalurkan melalui perl regex 90 karakter, hanya saja itu harus untuk menutup tiket. Sertakan pernyataan seperti, "Untuk penjelasan terperinci mengapa alur kerja ini terlihat seperti ini, ikuti tautan ini," dalam daftar periksa untuk mereka yang ingin tahu alasannya.

Poin kedua adalah untuk prosedur yang tidak sering dijalankan tetapi mengandung jebakan. Daftar periksa bertindak sebagai peta untuk menghindari Doom Tertentu hanya dengan menaruhnya. Jika daftar periksa disimpan dalam repo dokumentasi, ia harus mencari email untuk waktu admin lama mengirim HOWTO.

Dalam pendapat saya baik checklist-dokumentasi juga termasuk bagian dari poin mungkin kegagalan, dan tanggapan kepada mereka kegagalan. Ini dapat membuat dokumen agak besar dan memicu respons TL; DR pada rekan kerja, jadi saya menemukan bahwa menjadikan mode kegagalan dan respons mereka sebagai tautan dari daftar periksa daripada di halaman itu sendiri membuat daftar periksa yang tidak umum. Rangkul hipertualitas.

Dokumen sebagai Manual

Target pasar untuk dokumentasi semacam ini adalah orang-orang yang ingin belajar lebih banyak tentang cara kerja sistem. Dokumentasi style how-to-do-a-thing harus dapat diturunkan dari dokumentasi ini, tetapi lebih umum saya melihatnya sebagai suplemen untuk dokumentasi style checklist untuk mendukung keputusan yang dibuat dalam alur kerja.

Ini adalah dokumentasi di mana kami menyertakan potongan kenyal seperti:

• Menjelaskan mengapa ini dikonfigurasi dengan cara ini.
  • Bagian ini dapat mencakup masalah-masalah non-teknis seperti politik seputar bagaimana seluruh barang dibeli dan dipasang.
• Menjelaskan mode kegagalan umum dan responsnya.
• Menjelaskan perjanjian tingkat layanan apa pun, baik tertulis maupun de facto.
  • De facto: "jika ini gagal selama minggu final, itu masalah drop-everything. Jika selama liburan musim panas, kembali tidur dan berurusan dengan itu di pagi hari."
• Menyiapkan sasaran peningkatan dan refactoring.
  • Politik mungkin berbeda nanti, mengapa kita tidak memperbaiki beberapa ide buruk yang diperkenalkan di awal?

Yang semuanya sangat berguna untuk mendapatkan pemahaman komprehensif tentang keseluruhan sistem. Anda tidak memerlukan pemahaman yang komprehensif untuk menjalankan tugas otomasi manusia yang sederhana, Anda memerlukannya untuk mencari tahu mengapa ada sesuatu yang merusaknya dan memiliki ide di mana membuatnya tidak melakukan itu lagi.

Anda juga menyebutkan dokumentasi Pemulihan Bencana yang harus menjadi daftar periksa.

Saya mengerti, Anda memiliki simpati saya.

Ya, dokumentasi DR harus seperti checklist seperti mungkin.
Ya, dokumentasi DR adalah yang paling tahan terhadap daftar periksa karena berapa banyak hal yang dapat dipecahkan.

Jika daftar periksa DR Anda terlihat seperti:

1. Hubungi Dustin atau Karen.
2. Jelaskan masalahnya.
3. Mundur.

Anda punya masalah. Itu bukan daftar periksa, itu adalah pengakuan bahwa pemulihan sistem ini begitu rumit sehingga diperlukan seorang arsitek untuk mengetahuinya. Terkadang hanya itu yang bisa Anda lakukan, tetapi cobalah menghindarinya jika memungkinkan.

Dokumentasi DR idealnya berisi daftar periksa prosedur untuk beberapa hal yang berbeda:

• Prosedur Triage untuk mencari tahu apa yang salah, yang akan membantu mengidentifikasi ...
• Prosedur pemulihan untuk kasus kegagalan tertentu. Yang didukung oleh ...
• Skrip pemulihan ditulis dengan baik sebelumnya untuk membantu meminimalkan kesalahan manusia selama pemulihan.
• Dokumentasi gaya manual tentang kasus kegagalan, mengapa terjadi dan apa artinya.

Prosedur Triage kadang-kadang semua dokumentasi DR yang dapat Anda buat untuk beberapa sistem. Tetapi memiliki itu berarti panggilan keluar jam 4 pagi akan lebih mudah dipahami dan insinyur senior yang melakukan pemulihan akan dapat mengatasi masalah aktual dengan lebih cepat.

Beberapa kasus kegagalan memiliki prosedur pemulihan langsung. Dokumentasikan mereka. Saat mendokumentasikannya, Anda mungkin menemukan kasus di mana daftar perintah dimasukkan dalam urutan tertentu, yang merupakan kasus penggunaan yang bagus untuk skrip; dapat mengubah prosedur pemulihan 96 poin menjadi 20 poin. Anda tidak akan pernah tahu jika Anda dapat membuat skrip sesuatu hingga Anda memetakan tindakan prosedur pemulihan dengan tindakan.

Dokumentasi gaya manual untuk kasus-kasus kegagalan adalah penghalang parit terakhir yang digunakan ketika ADA prosedur pemulihan atau prosedur pemulihan gagal. Ini memberikan petunjuk-google yang diperlukan untuk mungkin menemukan orang lain yang memiliki masalah itu dan apa yang mereka lakukan untuk memperbaikinya.

Sebenarnya tidak satu pun, kami menggunakan Documentation As-a-Testcase

Yang sedang mengatakan kami memiliki dokumentasi tertulis yang pergi dengan Documentation As-a-Manual . Kami memiliki daftar periksa di tempat tetapi ketika tumbuh kami menemukan mereka menjadi rentan kesalahan dan benar-benar gagal pada sistem secara keseluruhan.

Namun kami memiliki semacam "Dokumentasi Sebagai-Checklist" yang diinstal, yaitu - sebagaimana disebutkan di atas - kami secara ekstensif memantau layanan kami. Ada pepatah:

Jika Anda tidak memonitornya, Anda tidak mengelolanya

Itu benar-benar benar, tetapi yang lain harus:

Jika Anda tidak memonitornya, Anda tidak mendokumentasikannya

Setiap kali kita perlu melakukan migrasi layanan, kita tetap membiarkan "Grup Layanan", "Grup Host", apa pun yang berlaku (kita menggunakan Nagios, seperti yang dapat Anda tebak dari kosa kata) terbuka dan itu tidak dimigrasi selama ada satu titik merah tunggal pada salah satu layanan.

Tes menyediakan daftar periksa yang jauh lebih baik daripada yang bisa diberikan oleh daftar periksa tulisan tangan mana pun. Ini benar-benar mendokumentasikan diri, segera setelah kami mengalami beberapa kegagalan yang tidak dipantau namun tes setidaknya akan ditambahkan ke Nagios, dengan itu kami mendapatkan 2 Hal gratis:

• kita tahu kapan itu gagal
• titik lain pada daftar periksa

Dokumentasi "asli" disimpan dalam Wiki yang menyebutkan peluang dan tujuan dari layanan atau tes tertentu. Jika hilang, orang akan menambahkannya segera setelah kami perlu melakukan migrasi atau perlu melakukan beberapa pekerjaan dengannya, sejauh ini pendekatan tersebut telah bekerja dengan sangat baik.

Dokumentasi yang tidak tepat juga disetrika dengan sangat cepat, setiap kali ada yang gagal orang mulai mencari dokumentasi dan mencoba untuk menyelesaikan masalah dengan HowTos di sana, jika salah perbarui saja dengan temuan Anda.

Bayangkan saja kesalahan yang bisa dibuat dengan mengikuti daftar periksa dan tidak menginstal tes apa pun yang akan memberi Anda kotak centang hijau setelah menerapkannya. Saya kira tidak mungkin memisahkan Dokumentasi dari Pemantauan.

Itu tergantung pada audiens target untuk dokumentasi Anda.

Untuk jenis helpdesk (level 1), daftar periksa adalah cara yang benar; tentu saja, ini mengandaikan bahwa ada tingkat dukungan yang lebih tinggi dengan pengetahuan yang lebih dalam yang Anda gambarkan.

Jika dokumentasi adalah untuk grup sistem, saya selalu keliru di sisi lebih banyak dokumentasi. Cukup sulit untuk memiliki dokumentasi yang memadai hanya untuk bertahan, jika seseorang (Anda) ingin menulis dokumen yang lebih luas dengan informasi latar belakang yang diperlukan - tidak ada orang waras yang boleh menghalangi Anda!

Secara pribadi saya mencoba dan menjaga dokumentasi sesederhana mungkin. Itu cenderung mencakup:

• Apa yang seharusnya [X] lakukan (persyaratan).
• Bagaimana [X] terstruktur pada level tinggi (desain).
• Mengapa saya menerapkan [X] dengan cara yang saya lakukan (pertimbangan implementasi).
• Bagaimana implementasi [X] adalah non-standar (solusi).
• Masalah umum dengan [X] dan cara mengatasinya (masalah).

Jadi harus diakui bahwa bagian masalah umum saya cenderung menjadi deskripsi singkat tentang apa yang telah terjadi dan penelusuran titik-titik tentang cara memperbaikinya.

Saya biasanya mengasumsikan beberapa pengetahuan dari pembaca sistem yang dimaksud (kecuali itu sangat misterius). Saya tidak punya waktu untuk membuat sebagian besar dokumentasi teknis saya level 1 atau manajemen dapat dibaca - tetapi level 3 yang jelas harus baik-baik saja.

Saya pikir itu jelas tergantung pada topiknya. Tidak semuanya dapat direduksi menjadi daftar periksa sederhana, dan tidak semuanya membutuhkan panduan pengguna yang terperinci.

Sepertinya Anda berbicara tentang dokumentasi internal, dan menurut pengalaman saya, Anda tidak bisa hanya memberikan daftar langkah, karena ada terlalu banyak pilihan. Bahkan membuat akun pengguna memiliki beberapa opsi (di lingkungan kami) sehingga dokumen "Akun Baru" kami mencantumkan langkah-langkah dasar secara berurutan, tetapi untuk setiap langkah memiliki deskripsi tentang apa variasinya.

Di sisi lain, kami tidak pernah sempat menulis banyak dokumen untuk "Cara menambal di kantor," tetapi dokumen kami yang sangat samar juga bukan daftar periksa - itu menyebutkan konvensi yang kami gunakan untuk warna kabel, menekankan Anda harus memperbarui spreadsheet yang mencantumkan koneksi, dan hanya itu saja.

Jadi, sekarang setelah saya menulis ini, saya sepenuhnya setuju: daftar periksa langkah-demi-langkah tidak akan memotongnya untuk banyak proses.

Saya sangat setuju dengan Anda tentang hal ini (mendukung dokumentasi yang lengkap) sebagian karena saya sudah terbiasa dengan pendahulu yang TIDAK memiliki banyak minat pada dokumen sama sekali. Seperti yang telah dikatakan dalam posting terkait, menulis itu tidak hanya baik untuk orang lain, tetapi membantu Anda untuk lebih memahami lingkungan Anda dan memadatkannya dalam pikiran Anda sendiri . Itu adalah akhir bagi dirinya sendiri.

Sebagai tambahan, saya menemukan bahwa banyak pushback berasal dari kepercayaan aneh bahwa dokumentasi jelek / tidak ada = keamanan kerja. Pemikiran seperti itu sepertinya tidak jujur ​​dan teduh.

Kudos kepada Anda untuk bucking status quo.

Saya mendokumentasikan cukup banyak, saya bahkan memiliki daftar periksa prioritas dokumen :-), namun saya tidak akan mendokumentasikan hal-hal yang dapat dianggap pengetahuan umum (yaitu deskripsi masalah yang masuk akal dan baik memberikan jawaban di halaman pertama google).

Bagi siapa pun yang tertarik di sini adalah checklist doc prio saya (berfungsi untuk saya, mungkin tidak untuk Anda, komentar dan saran sangat dihargai):

1. Buat log / buku harian pribadi yang Anda tuliskan semua yang Anda kerjakan / pengetahuan
2. Layanan, layanan mana, di mana, apa dan untuk siapa itu dilakukan (perjanjian SLA apa pun? Harus dibuat?)
3. Server, server apa, di mana, berapa umur dan kapan ditulis
4. Seperti di atas tetapi untuk peralatan jaringan, UPS dan sejenisnya
5. Seperti di atas tetapi untuk semua mesin pengguna
6. Layout dari jaringan fisik (kabel mana yang menuju, berapa lama dan berapa kualitas yang diukur)
7. Gambaran umum konfigurasi perangkat lunak dan lisensi untuk server
8. Tinjauan umum konfigurasi perangkat lunak dan lisensi untuk mesin pengguna
9. Ikhtisar konfigurasi sakelar, router, dan perangkat keras khusus lainnya
10. Kontrak dan SLA dari semua pihak eksternal yang untuknya layanan saya bergantung secara langsung (ISP, domain, dll.)
11. Atur sistem tiket dengan wiki terintegrasi untuk memasukkan semua hal di atas.
12. Untuk setiap kejadian buat tiket (bahkan jika Anda hanya menggunakannya untuk diri Anda sendiri).
13. Buat skrip yang pada hari Minggu mengumpulkan tiket dan mengelompokkannya berdasarkan jenis masalah.
14. Pada hari Senin buat solusi otomatis atau dokumentasi pengguna akhir untuk masalah yang paling sering terjadi
15. Jika waktu memungkinkan, lakukan yang berikutnya.
16. Jika tidak ada lagi yang harus dilakukan, cari pekerjaan baru dan berikan orang yang menggantikan Anda log ;-)

Daftar periksa baik-baik saja, asalkan tidak berpura-pura menjadi dokumentasi lengkap . Beberapa dokumen terakhir yang saya tulis datang dalam dua bagian: XYZ untuk Pengguna, yang mencakup tangkapan layar yang cantik tentang cara menggunakannya; dan XYZ untuk Administrator Sistem, yang mencakup cara pengaturannya, dan mengapa (bahkan mungkin termasuk persyaratan bisnis agar ada), perangkap yang harus dihindari, dan bagian tentang pemecahan masalah. Pemecahan masalah adalah tempat saya berharap menemukan daftar periksa. Mungkin menulis daftar periksa sebagai XYZ untuk Dukungan Teknis mungkin dapat membantu membuat titik.

Sekarang, membaca yang tersirat, hanya berfokus pada daftar periksa menunjukkan kepada saya kurangnya pemikiran "Gambaran Besar" dan perencanaan jangka panjang yang saya harapkan dari seseorang yang: hanya pernah melakukan dukungan teknis; atau admin junior yang baru memulai; atau begitu dibanjiri pekerjaan sehingga mereka tidak punya waktu untuk memikirkannya; atau tidak pernah didorong untuk memikirkannya; atau sekadar tidak peduli. Saya tidak tahu yang mana, jika ada, yang berlaku dalam kasus Anda.

Saya cukup besar dalam hal dokumentasi. Perusahaan tempat saya bekerja sekarang merasa bahwa dokumentasi itu penting, tetapi beberapa orang di perusahaan itu merasa mereka tidak punya waktu untuk menulis dokumentasi. Ini bisa membuat hidup lebih sulit bagi siapa pun selain orang yang semula melakukannya.

Untuk hal-hal tertentu, saya telah menulis instruksi langkah demi langkah. Anda dapat memanggil ini daftar periksa jika Anda mau, tetapi itu tidak benar-benar dimaksudkan untuk diperiksa secara fisik. Saya menyebut gaya dokumentasi saya "langkah TK". Itu berpola setelah buku latihan MCSE yang saya miliki untuk salah satu ujian Windows 2000. Langkah-langkahnya sangat terperinci, tetapi penggunaan huruf tebal / miring / huruf membuatnya mudah untuk ditutup-tutupi dan hanya memilih bagian-bagian penting sehingga Anda tidak perlu membaca semuanya setelah Anda mempelajari langkah-langkahnya.

Beberapa hal tidak sesuai dengan petunjuk langkah demi langkah, jadi saya mencoba memberikan sebanyak mungkin data konfigurasi. Seseorang yang cenderung teknis yang akhirnya mempertahankan jalannya akan memiliki gagasan yang lebih baik tentang apa yang mereka hadapi, dan mudah-mudahan itu akan membuat hidup mereka sedikit lebih mudah ketika terjadi kesalahan.