Memulai dengan dokumentasi

Kami belum melakukan dokumentasi di tempat kerja saya. Saya benar-benar baru untuk itu dan meminta beberapa panduan untuk memulai.

Saya punya beberapa pertanyaan:

• Apa dokumen-dokumen penting yang harus ditulis dan dipelihara sysadmin? Dan mengapa ini sangat penting?

• Bagaimana Anda menjaga dokumentasi Anda tetap sinkron dengan sistem? Bagaimana Anda meminimalkan duplikasi informasi?

• Panduan yang disarankan, praktik terbaik, anti-pola?

sejak 2003 saya mendokumentasikan semua yang ada di wiki internal kami.

Server

• spesifikasi perangkat keras
• informasi garansi
• informasi jaringan
• dan tentu saja menginstal perangkat lunak dan konfigurasi

Alur kerja

mis. cara menambah atau menghapus pengguna dan memberinya akses ke semua layanan yang relevan

Tautan penting

• tautan ke semua antarmuka web Anda
• tautan ke URL pemantauan (nagios, munin, apc-monitoring ...)
• tautan ke wiki (untuk versi cetak!)

Instruksi darurat

apa yang harus dilakukan jika server intranet / internet / server web / etc sedang down

Penting:

Pilih mesin wiki dengan ekspor mudah ke PDF!
Ini tidak berguna jika Anda sedang liburan, server yang menjalankan wiki Anda sedang down dan tidak ada yang tahu apa yang harus dilakukan karena dokumentasi Anda sedang luring

Lihatlah twiki, docuwiki atau mediawiki.

BTW:

ada plugin OpenOffice.org untuk menulis langsung ke mediawiki - sangat nyaman.

EDIT:

Juga bagus untuk menuliskan beberapa info /home/adminuser/maintenance. Ini dilakukan dengan cepat dan bisa sangat membantu, jika beberapa admin bekerja di server. misalnya:

2009-06-27 -thorsten-
          running aptitude update && aptitude full-upgrade
          everything seems ok
2009-06-25 -andreas-
          cups-pdf wasn't reachable. restarted cups
2009-06-23 -thorsten-
          deleted old log under /var/log/squid
etc.

Meskipun Anda menyadari bahwa sementara semua orang menginginkan (dan membutuhkan) dokumentasi, Anda juga perlu menyadari bahwa tidak ada yang punya waktu untuk membaca dan mempelajari hal-hal tersebut.

Jadi, jangan menulis dokumentasi yang perlu dipelajari - sebagai gantinya, susun dokumentasi Anda dengan cara yang memungkinkan seseorang untuk dengan cepat menemukan informasi yang mereka butuhkan, ketika mereka membutuhkannya - yang mungkin terjadi saat sistem mati dan CTO sedang. bernapas di lehernya.

Dengan pemikiran ini, beberapa saran ...

• Hindari blok teks yang besar
• Daftar peluru adalah teman Anda
• Diagram yang jelas adalah emas
• Pengulangan adalah ide yang bagus (1)
• Memudahkan memperbarui dan memperluas

(1) Jangan menciptakan satu sumber kebenaran dan memaksa orang untuk memburunya. Semakin penting idenya, semakin banyak Anda harus mengulanginya.

Dokumen penting:

• Dokumentasi server - spesifikasi / tata letak disk / perangkat lunak yang diinstal / catatan apa pun
• Prosedur umum - apa pun yang dilakukan yang bukan 'sepele' harus memiliki prosedur yang didokumentasikan, terutama jika itu adalah sesuatu yang belum pernah dilakukan sebelumnya.

Menjaga dokumentasi tetap sinkron bisa menjadi masalah 'perbaiki karena Anda melihat kesalahan'. Seiring dengan ini perlu datang kesadaran bahwa dokumentasi dapat dan akan ketinggalan zaman, dan bahwa itu tidak boleh diikuti secara membabi buta tanpa mempertimbangkan hal ini. Dokumentasi ada untuk membantu admin dalam tugas, bukan untuk menjadi langkah demi langkah set aturan yang menggantikan pemikiran kritis.

Meminimalkan duplikasi - menggunakan sesuatu seperti wiki di mana Anda dapat menautkan dokumentasi bersama dapat membantu dengan ini, alih-alih mengulangi informasi, Anda hanya menautkannya. Masalahnya adalah orang yang menulis dokumentasi perlu tahu bahwa informasi yang akan mereka duplikat sudah ada. Ini biasanya masalah organisasi yang baik.

Saya telah menemukan bahwa membuat template adalah bantuan besar. Dalam kasus saya ini adalah Templat Word tetapi gunakan apa pun yang cocok untuk Anda. Buat file kerangka, lengkap dengan bidang isian daftar dan bagian yang diinginkan. Setelah Anda menggunakannya beberapa kali, dan melakukan penyesuaian penyempurnaan, Anda akan membuat dokumen baru lebih cepat. Konsistensi format akan sangat membantu, baik untuk pembuatan dokumen dan penggunaan nanti. Dokumentasi perlu disimpan di tempat yang logis dan dalam struktur direktori logis.

Saya pribadi menentang pengulangan karena fakta sederhana bahwa itu membuat pemeliharaan tidak perlu sulit dan memakan waktu. Daripada menduplikasi dokumen, atau bagian dari dokumen, membuat referensi ke dokumen lain yang sesuai. Jika sesuatu berubah, Anda seharusnya tidak perlu mengubah dokumentasi yang relevan lebih dari sekali atau di lebih dari satu tempat, jika tidak, Anda akan memiliki koleksi dokumen yang saling bertentangan, yang tidak membantu siapa pun.

Saat membuat dokumentasi Anda, ingatlah untuk apa itu. Seseorang di lain waktu perlu menggunakannya. Apakah bisa digunakan untuk melakukan pekerjaan tanpa sepengetahuan sebelumnya?

Bukan jawaban langsung untuk pertanyaan Anda, tetapi penunjuk ke arah yang benar:

Saya menemukan Praktik Administrasi Sistem dan Jaringan , oleh Limoncelli dan Hogan (alias the Sysadmin Bible) cukup berharga karena ini tentang masalah "praktik terbaik", seperti dokumentasi. Jika Anda belum mengetahuinya, pastikan Anda menyelidikinya kapan pun Anda mendapat kesempatan.

Bagi saya, pertimbangan terpenting adalah membuatnya mudah digunakan. Jika sulit untuk mengatur maka orang akan menghindarinya. Saya memilih wiki Trac sebagai media dokumentasi kami karena alasan berikut:

• Terletak di pusat kota.

  Lebih dari satu salinan aktif dari satu dokumen apa pun menyebabkan kebingungan. Jika Anda dapat merujuk semua orang ke tempat yang sama, baik kontributor maupun audiens, maka Anda dapat menyederhanakan prosesnya.

• Pengeditan dan pemformatan sederhana.

  Begitu banyak waktu yang terbuang pada template Word yang cantik dan sesuai dengan gaya penulis terakhir. Jika Anda tidak menghalangi orang dengan ini, maka lebih mudah untuk mengedit saat bepergian dan kontributor lebih cenderung melakukannya. Pisahkan item sebanyak yang Anda inginkan dengan TracLinks.

• Riwayat audit.

  Penting untuk mengetahui siapa yang membuat perubahan, kapan dan mengapa. Jika Anda dapat mengikatnya ke tiket perubahan permintaan dan konfigurasi log komit maka bahkan lebih baik. Kait komit SVN sangat bagus untuk ini.