El Kitabı Olarak Dokümantasyon - Kontrol Listesi Olarak Dokümantasyon

Geçmişte bölümümdeki diğer kişilerle, özellikle ayrıntı düzeyi ve gereksinimler gibi belgeler hakkında tartışmalar yaptım. Onların görüşüne göre, X işleri yanlış gittiğinde yapılacaklar Y belgelerinin basit bir kontrol listesidir.

Katılmıyorum. Bunun BT'deki tüm sorunların kurtarma prosedürlerinin basit kontrol listelerine kolayca aktarılabileceğini varsayıyorum. Durumun karmaşıklığını tamamen görmezden geldiğini düşünüyorum ve bölümdeki diğer insanlar konuyla ilgili her zaman bir anlayış derinliğine sahip değiller (bu yüzden belgeyi yazıyorum - bu yüzden başvurulacak bir şeyleri var) ) belgelerin aşağıdaki gibi bazı temel arka plan materyallerini içermesi gerekir:

• Söz konusu (alt) sistemin amacı
• Neden bu şekilde yapılandırıldı
• Ayarlar / prosedürler uygulandığında gerçekleşecek olayların beklentileri
• Prosedürlerin başarısız olmasına neden olabilecek potansiyel konular

Bununla birlikte, bu konuda oldukça aşıldım, bu nedenle belgelerimin "ABC'nin uygulandığı adımlar X sorununu çözecek şekilde uygulanması" şeklinde bir forma yeniden yazılması gerekiyor . Sıklıkla tek bir kağıda sığması gereken ağıtları duyuyorum. Kalamar EKL'lerinin yapılandırmasını sorun giderme de dahil olmak üzere bu şekilde tek sayfalık bir belgeyle açıklamayı deneyin. Bu, kurtarma kontrol listeleri olarak "yazılmayı bekleyen" yarım düzine belgeden sadece biri.

Avukatlık ettiğim yöntem gerçekten abartılıyor mu? Yoksa haklılar mı ve işimi burada düşünmeli ve basit bir kontrol listesi yazmalıyım? Benim endişem, bir prosedür kontrol listesi ne kadar iyi yazarsanız yazın, gerçekten bir şeyler düşünmek için bir SysAdmin gerektiren bir sorunu çözmez. Sorunu çözmemekle sonuçlanan kurtarma prosedürlerinin bir kontrol listesini yapmak için zaman harcıyorsanız (belgenin dar odağı nedeniyle belgenin bir parçası olmayan ek faktörler olduğu için) ve sorunun amacı belge tekrar adam sayfaları ve wiki ve web sitelerini tekrar okumaktan kaçınmaktı, o zaman neden hareketlerden geçiyorum? Sadece çok mu endişeleniyorum, yoksa bu gerçek bir sorun mu?

DÜZENLE:

Bölümde şu anda yardım masası bulunmamaktadır. Belgelerin izleyicileri diğer yöneticiler veya bölüm başkanı içindir.

Benimkini yazarken hep iki üç set yazmaya başladım . İşlerin neden bu şekilde yapıldığını, çevrimiçi duruma geldiğinde muhtemel yapışmaları ve soyut tasarım varsayımlarını içeren, sistemin mimarisi hakkında ÇOK UZUN bir ekle birlikte , elde edilen kontrol listesi . ardından olası sorunların ve bunların çözümlerinin bir listesi ve ardından bir sistemin nasıl çalıştığı, neden bu şekilde çalıştığı hakkında bilgi içeren daha uzun bir bölüm ve insanları doğru yöne yönlendirmek için yararlı olan diğer bilgiler benzersiz bir şey olması gerekir.

Son işimde, 1. seviye yardım masası insanlarının bile işleri geri getirebilmesi için doktor yazmamız gerekiyordu. Bu, genellikle yazım tarihinden itibaren 3 ay içinde güncel olmayan kontrol listelerini gerektiriyordu. Mümkün olduğunca sorun giderme kılavuzları yazmamız şiddetle tavsiye edildi, ancak beklenmedik durum ağacı üçten fazla dal aldığında, bu dokümanı soyutlanmadan yazamazsınız.

Ne zaman terk benim son işi, ben 'nasıl benim işim yapmak' ben ayrılmadan önce kılavuzu 100 sayfa zorlandı. İçinde soyut şeyler, tasarım felsefesi ve entegrasyon noktaları vardı. Muhtemelen beni değiştirecek başka bir sistem yöneticisi için yazdığım için, soyut kavramları alıp somut eylemlere dönüştürebilecek birine yöneldim.

Beş yıl geçti ve bu konudaki fikrimin biraz değiştiğini görüyorum. Hem Manuel olarak Belge ve Kontrol Listesi olarak Belge belgelerin hiyerarşi ve üretilecek hem ihtiyacı çok değerli yerler var. Yine de çok farklı kitleleri hedefliyorlar.

Kontrol Listesi Olarak Belge

Bu tür belgeler için hedef pazar, bir şeyin nasıl yapılacağını öğrenmek isteyen iş arkadaşlarıdır. İki tiptirler:

• Sadece bir şeyin nasıl yapılacağını bilmek isteyen ve on beş sayfalık bir el kitabında gezinmek ve kendileri için adımları anlamak için vakti olmayan iş arkadaşları.
• Adımlar arasında oldukça karmaşık olan, ancak arada bir çalıştırılması gereken prosedürler.

Sabırsızlık ilk tür için itici güçtür. Belki de iş arkadaşınız , çıktının neden 90 karakter perl regex ile borulanması gerektiğini bilmek istemiyor , sadece biletin kapatılması için olması gerekiyor. Kesinlikle nedenini bilmek isteyenler için kontrol listesine "Bu iş akışının neden böyle göründüğüne ilişkin ayrıntılı bir açıklama için bu bağlantıyı izleyin" gibi bir ifade ekleyin.

İkinci nokta, sık sık çalıştırılmayan ancak tuzaklar içeren prosedürler içindir. Kontrol listesi, bazı kıyametin onu kanatlamasını önlemek için bir harita görevi görür. Kontrol listesi bir belge deposunda tutulursa, eski yöneticinin bir NASIL belgesi gönderdiği süre boyunca e-posta aramak zorunda kalmaz.

Bence iyi kontrol listesi dokümantasyonu olası hata noktaları ve bu arızalara verilen yanıtlar hakkında bölümler de içermektedir. Bu, belgeyi oldukça büyük hale getirebilir ve TL'yi tetikleyebilir; iş arkadaşlarınızdaki DR yanıtlarını, bu nedenle hata modlarını ve yanıtlarını sayfanın kendisinden ziyade kontrol listesinden bir bağlantı haline getirmenin sıra dışı bir kontrol listesi oluşturduğunu görüyorum. Hiper metinselliği kucaklayın.

Manuel Olarak Belge

Bu tür belgeler için hedef pazar, bir sistemin nasıl çalıştığı hakkında daha fazla bilgi edinmek isteyen kişilerdir. Bir şey nasıl yapılır tarzı belgeleri bu belgelerden türetilebilir olmalıdır, ancak daha çok iş akışında alınan kararları yedeklemek için denetim listesi tarzı belgelere ek olarak görüyorum.

Bu, aşağıdaki gibi çiğnenebilir parçaları dahil ettiğimiz belgelerdir:

• Neden bu şekilde yapılandırıldığını açıklamak.
  • Bu bölüm, her şeyin nasıl satın alındığını ve kurulduğunu çevreleyen politikalar gibi teknik olmayan konuları içerebilir.
• Yaygın hata modlarını ve yanıtlarını açıklama.
• Hem yazılı hem de fiili olarak herhangi bir hizmet düzeyi anlaşmasını açıklamak.
  • De facto: "Eğer final haftasında başarısız olursa, her şey bir damla sorunudur. Eğer yaz tatili sırasında, uykuya geri dönün ve sabah onunla başa çıkın."
• Yükseltme ve yeniden düzenleme hedefleri belirlemek.
  • Politika daha sonra farklı olabilir, neden başlangıçta ortaya çıkan bazı kötü fikirleri düzeltmiyoruz?

Tüm sistem hakkında kapsamlı bir anlayış elde etmek için hepsi çok yararlıdır. Basit insan otomasyon görevlerini yürütmek için kapsamlı bir anlayışa ihtiyacınız yoktur, bir şeyin neden böyle kırıldığını anlamanız ve bunu tekrar yapmamak için bir fikriniz olması gerekir.

Ayrıca, bir kontrol listesi olması gereken Olağanüstü Durum Kurtarma belgelerinden de bahsettiniz.

Anlıyorum, sempatilerim var.

Evet, DR belgelerinin mümkün olduğunca kontrol listesine benzer olması gerekir.
Evet, DR belgeleri, işlerin kaç yolu kırılabileceğinden dolayı kontrol listesine en dayanıklı olanıdır.

DR kontrol listeniz aşağıdaki gibi görünüyorsa:

1. Dustin veya Karen'ı ara.
2. Sorunu açıklayın.
3. Geri çekil.

Bir sorunun var. Bu bir kontrol listesi değil, bu sistemin kurtarılmasının o kadar karmaşık olduğunu kabul etmek bir mimarı bulması gerekiyor. Bazen tüm yapabileceğiniz budur, ancak mümkünse bundan kaçınmaya çalışın.

İdeal olarak DR belgeleri birkaç farklı işlem için prosedür kontrol listeleri içerir:

• Neyin yanlış gittiğini tespit etmek için triyaj prosedürleri ,
• Belirli arıza durumları için kurtarma prosedürleri. Hangi tarafından desteklenmektedir ...
• Kurtarma sırasında insan hatasını en aza indirmeye yardımcı olmak için önceden yazılmış kurtarma komut dosyaları.
• Arıza durumları, neden ortaya çıktıkları ve ne anlama geldikleri hakkında manuel tarzı belgeler.

Triyaj prosedürleri bazen bazı sistemler için yapabileceğiniz tüm DR dokümanlarıdır. Ancak bunun olması, 04:00 çağrısının daha anlaşılır olacağı ve kurtarma işlemini yapan kıdemli mühendisin gerçek soruna daha hızlı ulaşabileceği anlamına gelir.

Bazı arıza vakaları, doğrudan kurtarma prosedürlerine sahiptir. Belgeleyin. Bunları belgelendirirken, komut listelerinin belirli bir sırada girildiği durumları bulabilirsiniz; bu, komut dosyası oluşturmak için harika bir kullanım örneğidir; 96 nokta kurtarma prosedürünü 20 noktaya dönüştürebilir. Kurtarma yordamı eylemini eylem ile eşleştirene kadar bir şey komut dosyası yazıp yazamayacağınızı asla anlamazsınız.

Arıza durumları için manuel tarzdaki belgeler, kurtarma prosedürleri olmadığında veya kurtarma prosedürleri başarısız olduğunda kullanılacak son hendek geri döndürmezidir. Belki de bu sorunu yaşayan birini bulmak ve düzeltmek için ne yaptıklarını bulmak için gereken Google ipuçlarını sağlar.

Aslında hiçbirini Testas Olarak Belgeler kullanmıyoruz

Bununla birlikte, Manuel Olarak Dokümantasyon ile ilgili dokümanları yazdık . Kontrol listeleri vardı ama büyürken hataya meyilli olduklarını ve sistemde bir bütün olarak başarısız olduklarını gördük.

Bununla birlikte, bir çeşit "Kontrol Listesi Olarak Doküman Listesi" kurulu, yani - yukarıda belirtildiği gibi - hizmetlerimizi kapsamlı bir şekilde izliyoruz. Bir söz var:

Eğer izlemiyorsanız yönetmiyorsunuz

Bu tamamen doğru, ama bir tane daha olmalı:

İzlemiyorsanız, belgelemiyorsunuz

Hizmetleri taşımamız gerektiğinde, yalnızca "Hizmet Grubu", "Ev Sahibi Grup", ne olursa olsun (kelime dağarcığından tahmin edebileceğiniz gibi Nagios kullanıyoruz) açık tutuyoruz ve tek bir kırmızı nokta olduğu sürece taşınmıyor herhangi bir hizmet.

Testler, elle yazılmış herhangi bir kontrol listesinin sağlayabileceğinden çok daha iyi bir kontrol listesi sağlar. Aslında kendi kendini belgeliyor, henüz izlenmeyen bazı hatalarımız olur olmaz, test en azından Nagios'a eklenecek, bununla birlikte ücretsiz 2 Şey alıyoruz:

• ne zaman başarısız olduğunu biliyoruz
• kontrol listesindeki başka bir nokta

"Gerçek" belgeler, belirli bir hizmetin veya testin olasılıklarından ve sonlarından bahseden bir Wiki'de tutulur. Eğer eksikse, insanlar bir miktar göç yapmamız gerektiğinde veya onunla biraz çalışmamız gerektiğinde ekleyecekler, şimdiye kadar bu yaklaşım çok iyi çalıştı.

Ayrıca hatalı belgeler gerçekten hızlı bir şekilde ütülenir, bir şey başarısız olduğunda insanlar belgeleri aramaya başlar ve orada HowTos ile sorunu çözmeye çalışır, eğer yanlışsa sadece bulgularınızla güncelleyin.

Sadece bir kontrol listesini takip ederek ve uyguladıktan sonra size yeşil bir onay kutusu verecek herhangi bir test yüklememiş olmanızın olası hataları düşünün. Belgeleri İzleme'den ayırmanın mümkün olduğunu düşünmüyorum.

Belgeleriniz için hedef kitleye bağlıdır.

Yardım masası (düzey 1) türleri için, bir denetim listesi gitmek için doğru yoldur; Tabii ki, bu, tanımladığınız daha derin bilgilerle daha yüksek düzeyde destek olduğunu varsayar.

Belgeler sistem grubu içinse, her zaman daha fazla belgenin yanında hata yaparım. Birisi (kendiniz) gerekli arka plan bilgileriyle daha kapsamlı dokümanlar yazmak istiyorsa, sadece geçinmek için yeterli belgelere sahip olmak yeterince zordur - aklı başında bir kimse yolunuza çıkmamalıdır!

Şahsen dokümantasyonu olabildiğince basit tutmaya çalışıyorum. Şunları içerir:

• [X] ne yapmalı (gereksinimler).
• [X] 'in yüksek seviyede nasıl yapılandırıldığı (tasarım).
• Neden [X] 'i benim yaptığım şekilde uyguladım (uygulama hususları).
• [X] 'un uygulanması standart değildir (geçici çözümler).
• [X] ile ilgili genel sorunlar ve bunların nasıl çözüleceği (sorunlar).

Kuşkusuz, ortak sorunlar bölümüm, neler olduğunu ve nasıl düzeltileceğine dair nokta noktası izlenecek yolların kısa bir açıklaması olacaktır.

Genelde söz konusu sistemin okuyucusundan bazı bilgiler olduğunu varsayıyorum (özellikle gizli değilse). Teknik dokümantasyon düzey 1 veya yönetimimin çoğunu okunabilir hale getirmek için zamanım yok - ancak 3. seviye bir ipucunun iyi olması gerekir.

Açıkçası konuya bağlı olduğunu düşünüyorum. Her şey basit bir kontrol listesine indirgenemez ve her şeyin ayrıntılı bir kullanım kılavuzuna ihtiyacı yoktur.

Kesinlikle dahili dokümantasyondan bahsediyormuşsunuz gibi geliyor ve tecrübelerime göre sadece bir adım listesi veremezsiniz, çünkü çok fazla seçenek var. Bir kullanıcı hesabı oluşturmanın bile bazı seçenekleri vardır (ortamımızda), bu nedenle "Yeni Hesap" dokümanımız temel adımları sırayla listeler, ancak her adım için varyasyonların ne olduğuna dair bir açıklama vardır.

Öte yandan, "Bir ofiste nasıl yama yapılır" için bir belgenin çoğunu yazmak için hiç uğraşmadık, ancak çok kabataslak belgemiz de bir kontrol listesi değildi - kabloların renkleri için kullandığımız konvansiyondan bahsetti. bunu vardı bağlantıları listelenen-tabloyu güncellemek için, ve bu konuda oldu.

Yani, şimdi bunu yazdım, tamamen katılıyorum: adım adım kontrol listeleri çok fazla işlem için kesmeyecek.

Kısmen bu konuda (tamamen kapsamlı belgeler lehine) katılıyorum, çünkü belgelere fazla ilgi duymayan öncüllere alışkınım. İlgili yayınlarda söylendiği gibi, bunu yazmak sadece diğerleri için iyi değildir, aynı zamanda ortamınızı daha iyi anlamanıza ve onu kendi zihninizde sağlamlaştırmanıza yardımcı olur . Bu kendi başına bir son.

Bir kenara, geri itmenin birçoğunun boktan / var olmayan belgelerin = iş güvenliği olduğuna dair garip bir inançtan geldiğini görüyorum. Bu tür düşünceler sahtekâr ve gölgeli görünüyor.

Statükoyu bozduğun için sana şeref.

Ben oldukça çok belge, ben bile bir belge öncelik kontrol listesi :-) var, ancak ben jenerik bilgi olarak kabul edilebilir şeyler belge olmaz (yani sorunun makul iyi bir açıklama google ilk sayfasında bir cevap verir).

Burada ilgilenen herkes için benim doktor prio kontrol listem (benim için çalışıyor, sizin için olmayabilir, yorum ve öneriler çok takdir edilmektedir):

1. Yaptığınız her şeyi / bilgiyi akıllıca yazdığınız kişisel bir günlük / günlük oluşturun
2. Hizmetler, hangi hizmet nerede, ne ve kim için yapılır (herhangi bir SLA sözleşmesi oluşturulmalı mı?)
3. Sunucular, hangi sunucu nerede, kaç yaşında ve ne zaman yazılıyor
4. Yukarıdaki gibi fakat ağ ekipmanı, UPS ve benzerleri için
5. Yukarıdaki gibi ancak tüm kullanıcı makineleri için
6. Fiziksel ağın yerleşimi (hangi kablo nereye gider, ne kadar sürer ve ölçülen kalite nedir)
7. Sunucular için yazılım ve lisansların yapılandırmasına genel bakış
8. Kullanıcı makineleri için yazılım ve lisansların yapılandırmasına genel bakış
9. Anahtarlar, yönlendiriciler ve diğer özel donanımların yapılandırmasına genel bakış
10. Hizmetimin doğrudan bağlı olduğu tüm harici tarafların sözleşmeleri ve SLA'ları (ISS, alan adı vb.)
11. Yukarıdaki tüm şeyleri içine koymak için entegre wiki ile bir bilet sistemi kurun.
12. Her olay için bir bilet oluşturun (sadece kendiniz için kullansanız bile).
13. Pazar günü bilet toplayan ve problem tipine göre gruplandıran bir senaryo oluşturun.
14. Pazartesi günü en sık karşılaşılan sorun için otomatik bir çözüm veya son kullanıcı nasıl yapılır belgesi oluşturun
15. Zaman izin verirse bir sonrakini yapın.
16. Yapacak başka bir şey yoksa, yeni bir iş arayın ve günlüğün yerine geçen kişiye verin ;-)

Tam bir belge gibi davranmadığı sürece bir kontrol listesi iyidir . Yazdığım son birkaç belge iki bölümden oluştu: Kullanıcılar için XYZ, nasıl kullanılacağına dair güzel ekran görüntüleri içeriyordu; ve Sistem Yöneticileri için XYZ, nasıl kurulduğunu ve neden (muhtemelen var olması için iş gereksinimini de dahil), kaçınılması gereken tuzakları ve sorun giderme hakkında bir bölümü içerir. Sorun giderme, kontrol listelerini bulmayı beklediğim yerdir. Belki de kontrol listelerini Teknik Destek için XYZ olarak yazmak bir noktaya değinmeye yardımcı olabilir.

Şimdi, satırlar arasında okumak, sadece kontrol listelerine odaklanmak için bana "Büyük Resim" düşüncesi ve uzun vadeli planlama eksikliğini gösteriyor ki: Sadece teknik destek yapmış; veya yeni başlayan bir yönetici; ya da iş ile bu kadar bataklık içinde olduğunu düşünecek zamanları yok; ya da hiç düşünmeye itilmemiş; ya da sadece sade umurunda değil. Davanızda bunlardan hangisinin geçerli olduğunu bilmiyorum.

Dokümantasyon konusunda oldukça büyüküm. Şu anda çalıştığım şirket dokümantasyonun önemli olduğunu düşünüyor, ancak şirketteki bazı insanlar dokümantasyon yazmak için zamanları olmadığını düşünüyor. Bu, başlangıçta bunu yapan kişinin yanı sıra, herkes için hayatı zorlaştırabilir.

Bazı şeyler için adım adım talimatlar yazdım. İsterseniz buna bir kontrol listesi diyebilirsiniz, ancak fiziksel olarak kontrol edilmesi amaçlanmamıştır. Belgeleme tarzımı "anaokulu adımları" olarak adlandırıyorum. Windows 2000 sınavlarından biri için aldığım bir MCSE alıştırma kitabından sonra düzenlenmiştir. Adımlar çok ayrıntılıdır, ancak kalın / italik / yazı tipi kullanımı, parlaklığı kolaylaştırır ve önemli parçaları seçmenizi sağlar, böylece adımları öğrendikten sonra her şeyi okumanız gerekmez.

Bazı şeyler adım adım talimatlara iyi uymuyor, bu yüzden olabildiğince fazla yapılandırma verisi sağlamaya çalışıyorum. Teknik bakımdan eğimli olan ve yolun bakımını yapan bazı kişiler, neyle karşı karşıya oldukları hakkında daha iyi bir fikre sahip olacaklar ve umarım bir şeyler ters gittiğinde hayatlarını biraz daha kolaylaştıracaktır.