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.
sumber
Jawaban:
Saat menulis milik saya, saya selalu beralih ke menulis
duatiga 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:
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:
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:
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 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.
sumber
don't have time
bisa jadidon't have time
. Secara keseluruhan, pengalaman yang dapat digunakan kembali!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:
Itu benar-benar benar, tetapi yang lain harus:
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:
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.
sumber
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!
sumber
Secara pribadi saya mencoba dan menjaga dokumentasi sesederhana mungkin. Itu cenderung mencakup:
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.
sumber
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.
sumber
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.
sumber
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):
sumber
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.
sumber
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.
sumber