Heck'i her şeyin dışında belgeleyin.
Son zamanlarda Slashdot'ta belgelerin başlatılmasıyla ilgili bir konu vardı ve bu da belgelerle ilgili düşüncelerimi yazmam için bana ilham verdi.
Anahtar noktalarım:
İlke # 1: Asla Yapılmadı
Belgeleme, sürekli olarak üretimde olanın gerisinde kalacak bir çaba. Değişiklikler geçici yapılır, işler taşındı ya da üretilmiyor ya da rastgele hizmete sokuluyor. Belgeler asla yetişmeyecek.
Faturaları ödeyen kişilere, çalışan belgeleri güncel tutmak için harcadıkları zamanın (ve dolayısıyla paranın) değeri üzerinden satmak zorundasınız. Sık sık bu konuşmalar şöyle devam eder: "$ TIME’ın $ THING’in nasıl kırıldığını bulmak için $ TIME harcamak zorunda kaldığımı hatırla? hepsini çözmek zorundayım. "
Bunu yapmalısın, asla bitmeyeceksin bile.
İlke # 2: Dokümantasyon Olmamasından Kötü Olan Tek Şey Yanlış Dokümantasyon
Bu bir prensipten çok bir gerçekçiliktir. Belgeleme, bir şeyin bilinen bir durumda olduğu ve bir şey yanlış giderse, onu düzeltmeye devam etmeye başlayabileceğiniz konusunda yanlış bir anlam ifade etmenize neden olabilir.
Bu sorunu kabul etmek önemlidir.
İlke # 3: Halefinize Belge Yazıyorsunuz
Oranlar, bir daha başvurmak zorunda kalmayacağınız bir belge yaptığınız işlerin% 95'idir. Belgeleme, sizin için değil, gelecek için bir bilgelik koleksiyonudur. Dolayısıyla, izleyicilerinizin, olayların nasıl oldukları ile ilgili özellikleri hakkında çok az şey bildiğini veya hiçbir şey bilmediğini varsaymalısınız.
Ve bir halef olacak. Seni bilmem ama hayatım boyunca bu belirli ortamlarda olmayı planlamıyorum. Fırsatlar gelir ve gider ve geldiklerinde bazen gidersiniz. Fakat hayat arkanızda devam eder ve halefiniz için hayatı daha iyi hale getirebileceğiniz pürüzsüzlük artar. Aksi taktirde, sessizce sizinle ilgili rahatsız edici şeyler söyleyen eski müşterilerden oluşan bir koleksiyonunuz olabilir. Ottawa’nın her yerinde IT’de her yerde çalışan 50 kişinin aynı olduğunu söylemek hoşuma gidiyor. Halefinize yardım etmek gelecekte sizin için kapılar açabilir.
Şimdi belli bir dereceye kadar sorun çıkınca her zaman bir miktar "önceki adamı suçlama" vardır. Bu işin bir parçası. Kendim yaptım. Fakat birkaç kez, önceki adamı bir tür moron olarak patlattığım zaman, başka türlü bir şey yaptığını ve o zamanlar olduğumdan ne olup bittiğini daha fazla bildiğini öğrendim.
İlke # 4: “Neden” genellikle “Nasıl” dır
Bir sisteme bakarken çoğumuz, neden böyle bir cehennem olduğunu düşünmeye başlıyoruz? Yapılandırma seçimlerinin neredeyse her zaman çok özel nedenleri vardır. Bu durumlarda, "Neden", "Nasıl" kelimesini belirler ve okuyucunun, çözümünüzün sigara bırakma kalıntılarını incelerken çözülen belirli sorunları anladığından emin olmalısınız.
İlke # 5: Kolay olmalı ya da yapmayacaksınız
Bu, araçlarınızı ve araçlarınızı kullanacak olanların farkında olmanız gerektiği anlamına gelir.
Olayları güncel tutmak kolay olmalı. Herhangi bir çaba sarf etmeniz gerekiyorsa, bir değişiklikten hemen sonra yapılan en iyi şekilde yapılmasından kaçınmak için bahaneler bulabilirsiniz.
Araçlarınız başkalarının kullanması için kolay değilse, kullanmazlar. Bu, özellikle takım ortamında sakatlanabilir, çünkü takım büyüdükçe, araç seçiminizi sevmeyen bir takım üyesine daha fazla rastlarsınız.
Şahsen ben belgeler için bir wiki severim. Ancak sorun şu ki, bir wiki size bir yapıyı zorlamıyor, bu yüzden yapı dışardan dayatılmalıdır. Bu her zaman başka bir yerde daha iyi / farklı bir fikre sahip olduğu için bir yerlerde çatışmaya neden olur.
Bazı yerlerde "PDF" için "yayınlanan" ve "en son" PDF'nin yetkili olduğu düşünülen Word ve Visio belgelerini kullandım. İşvereninize / halefinize verebileceğiniz bir koleksiyona sahip olmanız iyi bir şey. PDF'ler, doğru şekilde düzenlenmişse, gezinmesi kolay olmamakla birlikte, olanların tarihsel bir kaydını sağlayabilir. Word veya Visio'dan hoşlanmadığım ve fikirleri etkili bir şekilde iletebilmek için bu araçların temelini anlama zorunluluğum olması kötü.
Şu andaki işverenim, Sharepoint portalındaki Word belgeleri fikriyle oynuyor. Oraya ne kadar uzağa gittiğimizi görmek zorundayız