Memulai dengan dokumentasi

21

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?

chickeninabiscuit
sumber

Jawaban:

15

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.
ThorstenS
sumber
2
+1 untuk petunjuk mundur jika wiki sedang down.
Manuel Faux
Apa itu OOo? Sepertinya OpenOffice, tapi saya tidak tahu "o" terakhir. Jika Anda bisa memberi nama plugin, itu akan bagus.
Daniel C. Sobral
3
benar, OOo adalah OpenOffice.org ;-) Ekstensi: extensions.services.openoffice.org/de/project/wikipublisher
ThorstenS
13

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.

Bevan
sumber
2
Namun, dengan lebih dari satu sumber dokumentasi, Anda memiliki lebih dari satu tempat yang perlu diperbarui jika sudah usang dan perlu diubah. Cara yang baik untuk menyelesaikan ini (jika Anda memiliki wiki atau yang serupa) adalah mencoba membuat satu sumber kebenaran sejati dan menautkannya dari sebanyak mungkin tempat yang diperlukan.
Markus
Sampai batas tertentu, saya setuju - tautan dan referensi silang memang sangat berguna. Ada trade-off meskipun - dalam desain database, itu biasa untuk mendeormalisasi tabel untuk membantu dalam pelaporan. Saya pikir pendekatan yang sama relevan di sini - untuk membuat konsumsi dokumentasi lebih mudah, mengulangi fakta-fakta kunci bisa berharga.
Bevan
boleh saja mendistribusikan prinsip secara luas, tetapi untuk hal-hal seperti alamat IP, kata sandi, manajemen konfigurasi sumber data tunggal yang otoritatif dan terpusat, dengan cadangan yang memadai adalah kunci administrasi yang waras.
Tom H
Saya setuju - selama ini terkenal dan mudah diakses - satu sumber rahasia otoritatif adalah antipattern yang terlalu umum.
Bevan
Saya sangat tidak setuju dengan pengulangan, karena satu akan diperbarui, tetapi yang lain tidak. Atau mereka akan diperbarui secara tidak konsisten. Sebaliknya dokumen yang lebih penting harus lebih mudah dihubungkan .
gWaldo
5

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.

Menandai
sumber
4

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?

John Gardeniers
sumber
3

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.

Tiberiu Ana
sumber
Edisi ke-2 buku itu memiliki bab tentang dokumentasi. Buku terkait, "Manajemen Waktu untuk Administrator Sistem" memiliki bab tentang dokumentasi yang lebih fokus pada apa yang perlu Anda lakukan, daripada apa yang perlu dilakukan organisasi Anda.
TomOnTime
0

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.

Dan Carley
sumber
Saya juga menggunakan trac untuk dokumentasi satu proyek. Yang benar-benar hilang adalah sejenis remah roti di wiki. Saya harap ini akan segera datang.
ThorstenS