Belgelere başlarken

İşyerimde hiçbir belge yapmadık. Tamamen yeniyim ve başlamak için rehberlik isteyin.

Bir kaç sorum var:

• Bir sistem yöneticisinin yazması ve bakımını yapması gereken temel belgeler nelerdir? Ve bunlar neden bu kadar önemli?

• Belgelerinizi sistemle nasıl senkronize edersiniz? Bilgilerin kopyalanmasını nasıl en aza indirirsiniz?

• Önerilen kılavuzlar, en iyi uygulamalar, anti-paternler?

2003'ten beri kurum içi wiki'mizdeki her şeyi belgeliyorum .

Sunucular

• donanım özellikleri
• garanti bilgileri
• ağ bilgisi
• ve tabii ki kurulu yazılım ve yapılandırma

İş Akışları

örneğin bir kullanıcı nasıl eklenir veya silinir ve ona ilgili tüm hizmetlere nasıl erişim verilir

Önemli bağlantılar

• tüm web arayüzlerinize bağlantı
• izleme URL'lerine bağlantı (nagios, munin, apc-izleme ...)
• wiki'ye bağlantı (basılı sürüm için!)

Acil durum talimatları

intranet sunucusu / internet / web sunucusu / vb. çalışmıyorsa ne yapmalı

Önemli:

PDF'ye kolay dışa aktarma ile bir wiki motoru seçin!
Tatil içindeyseniz, wiki'nizi çalıştıran sunucu çalışmıyor ve belgeleriniz çevrimdışı olduğu için kimse ne yapacağını bilmiyor

Twiki, docuwiki veya mediawiki'ye bir göz atın.

BTW:

doğrudan mediawiki'ye yazmak için bir OpenOffice.org eklentisi var - çok uygun.

DÜZENLE:

Ayrıca bazı infos yazmak güzel /home/adminuser/maintenance. Bu hızlı bir şekilde yapılır ve birkaç yönetici bir sunucuda çalışırsa çok yardımcı olabilir. Örneğin:

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.

Herkes dokümantasyon isterken (ve ihtiyaç duyarken), hiç kimsenin bu bilgileri okumak ve incelemek için zamanının olmadığını bilmeniz gerekir.

Bu nedenle, incelenmesi gereken belgeleri yazmayın - bunun yerine, belgelerinizi birisinin ihtiyaç duydukları bilgileri, ihtiyaç duydukları anda hızlı bir şekilde bulabilecek şekilde yapılandırın - sistem kapalıyken ve CTO boynunu soluyor.

Bunu akılda tutarak, bazı öneriler ...

• Büyük metin bloklarından kaçının
• Mermi listeleri senin arkadaşın
• Açık bir diyagram altındır
• Tekrarlama iyi bir fikirdir (1)
• Güncellemeyi ve genişletmeyi kolaylaştırın

(1) Tek bir gerçeklik kaynağı yaratmayın ve insanları onu avlamaya zorlamayın. Fikir ne kadar önemli olursa, o kadar çok tekrar etmelisiniz.

Temel dokümanlar:

• Sunucu belgeleri - özellikler / disk düzenleri / yüklü yazılım / not edilen herhangi bir şey
• Ortak prosedürler - 'önemsiz' olmayan bir şey, özellikle de daha önce yapılmayan bir şeyse, belgelenmiş bir prosedüre sahip olmalıdır.

Belgeleri senkronize tutmak, hemen hemen 'hataları gördüğünüz gibi düzeltin' meselesi olabilir. Bununla birlikte, belgelerin güncelliğini yitirebileceği ve güncel olamayacağı ve bunu dikkate almadan körü körüne takip edilmemesi gerektiği gerçeği ortaya çıkmalıdır. Belgeler, bir yöneticiye görevlerde yardımcı olmak için eleştirel düşüncenin yerini alan adım adım kurallar olmamasına yardımcı olur.

Çoğaltmayı en aza indirme - belgeleri birbirine bağlayabileceğiniz wikis gibi bir şey kullanmak, bu konuda yardımcı olabilir, bilgileri tekrarlamak yerine, sadece bağlantı verirsiniz. Sorun, belgeleri yazan kişinin çoğaltmak üzere oldukları bilginin zaten var olduğunu bilmesidir. Bu genellikle iyi bir organizasyon meselesidir.

Bir şablon oluşturmanın büyük bir yardım olduğunu gördüm. Benim durumumda bir Word şablonu ama size uygun olanı kullanın. İçindekiler alanı ve bölümlerle istediğiniz gibi bir iskelet dosyası oluşturun. Birkaç kez kullandıktan ve ince ayarlamalar yaptıktan sonra, yeni belgeleri çok daha hızlı oluşturacaksınız. Biçimin tutarlılığı, hem belge oluşturma hem de daha sonra kullanım için çok yardımcı olacaktır. Belgelerin mantıksal bir yerde ve mantıksal bir dizin yapısında saklanması gerekir.

Ben şahsen gereksiz yere bakım zor ve zaman alıcı hale basit gerçeği için tekrar karşıyım. Yinelenen belgeler veya belge bölümleri yerine, uygun olduğunda diğer belgelere referanslar oluşturun. Şey, daha sonra bir veya birden fazla yerde ilgili belgeleri değiştirmek zorunda asla değiştirirse, aksi takdirde olacak kimse yardımcı olur çelişkili belgeler koleksiyonu var.

Belgelerinizi oluştururken bunun ne için olduğunu unutmayın. Daha sonra birinin kullanması gerekecek. İşi önceden bilgi sahibi olmadan yapmak kullanılabilir mi?

Sorunuza doğrudan bir cevap değil, doğru yönde bir işaretçi:

Limoncelli ve Hogan'ın (Sysadmin İncil'i) Sistem ve Ağ Yönetimi Uygulamasını oldukça değerli buldum çünkü dokümantasyon gibi "en iyi uygulama" konuları ile ilgili. Henüz bilmiyorsanız, fırsat bulduğunuzda araştırdığınızdan emin olun.

Benim için en önemli husus kullanımı kolaylaştırmak. Düzenlemek zorsa, insanlar bundan kaçınacaktır. Trac'ın wiki'sini belgelerimiz için aşağıdaki nedenlerle seçiyorum :

• Merkezi konumda.

  Herhangi bir belgenin birden fazla aktif kopyası karışıklığa yol açar. Herkesi hem katılımcılara hem de izleyiciye aynı yere yönlendirebiliyorsanız, süreci basitleştirebilirsiniz.

• Basit düzenleme ve biçimlendirme.

  Güzel Word şablonlarında ve son yazarın stiline uygun olarak çok zaman harcanıyor. İnsanları bununla boğuşmazsanız, hareket halindeyken düzenlemek daha kolaydır ve katkıda bulunanlar bunu yapmaya daha meyillidir. TracLinks ile öğeleri istediğiniz kadar ayırın.

• Denetim geçmişi.

  Kimin neyi, ne zaman ve neden değiştirdiğini bilmek önemlidir. Eğer değişiklik istek biletleri ve yapılandırma taahhüt günlüklerine bağlayabilirsiniz eğer daha iyi. SVN taahhüt kancaları bunun için mükemmeldir.