Başka birinin geçmiş çalışmalarını nasıl belgeleyebilirim? [kapalı]

Geçmiş çalışanlarımızın iş açısından kritik bir sistemde yaptıkları özelleştirme konusunda çok az dokümantasyona sahip olmak kötü bir durumdayız. ERP yazılımımız için Crystal Reports, veritabanı varlıkları ve özel yapılandırma / programlama dosyalarında çok sayıda değişiklik yapıldı.

Mevcut belgeler genellikle şöyle bir şey okur:

Bu program faturalandırmadan önce çalıştırılır. Bilinen hatalar: yok.

X yazılımını kurduktan sonra bu programı çalıştırın.

Bu rapordaki aşağıdaki alanlar değişti: (nasıl veya neden olduğuna dair açıklama olmadan)

BT mağazamız küçük ve ERP yazılımı söz konusu olduğunda, çoğu iş bir kişi üzerinde toplandı (şimdi benim), bu yüzden burada kimse ne yaptığımızı bilmiyor. BT ve muhasebe departmanı bitleri ve parçaları (bazen oldukça yararlı olanlar) bilir, ancak yeterli değildir.

Başka bir sorun Muhasebe departmanımızın iyi belgelendiğimizi düşünüyor olması . Neyin yanlış gittiğine dair çok sayıda kayıt tuttuğumuz doğrudur , ancak bu sorunları çözmek için ne yapıldığını (eğer varsa) çok az açıklıyor. Hataları açıklayan yüzlerce makalemiz var, ancak değişiklikleri açıklayan belgeler (yukarıda gösterildiği gibi) neredeyse işe yaramaz.

Ne yapıldığını bilmediğimde geçmiş değişiklikleri belgelemeye nasıl devam edebilirim? Neyi değiştirdiğimizi belgelemeye başlayabilirim : Dosyalar, veritabanı tabloları vb. Sistemin çalışması için ihtiyacımız olan şey. Ayrıca biz neyi belgelenebilir yapmak ; raporlar çalıştırıldığında, insanlara neden X raporu / programı kullanmaları söylendi. Ancak bu özelleştirilmiş şeylerden birinin bir sorunu olduğunda, her zaman kareye geri dönerim.

Bu şeyleri kendim ve başkaları için nasıl proaktif olarak belgeleyebilirim?

Bence bu nafile bir alıştırma. Çalışırsa çalışır, işe yaramazsa, düzeltmeniz gerekir.

Eski şeyleri belgelemenin en iyi yolu, üzerinde çalışırken, ne yaptığınızı belgelemek ve iş mantığını açıklamaktır (ki belgelenmediğini varsayıyorum). Bu, herhangi bir yeni geliştirici için büyük bir yardımcı olacaktır.

Eski kodu / şeyleri belgelemekten bahsetmişken, birinin buna sahip olması gerekiyordu. Bunun şu anki yöneticiniz olduğunu varsayalım. Bununla ilgili tam teknik bilgiye sahip olmayabilir, ancak hangi değişikliklerin yapıldığını bilecektir. Bu durumda, bu sizin işiniz değildir. Yönetici ne değişiklikler yapıldığı hakkında bir şeyler yazabilirsiniz. Bu, tarih olarak saklanmakta yardımcı olur. Böyle bir sorun ortaya çıkarsa, bu alanlara girebilirsiniz, bu size çok yardımcı olabilir. Ancak kod ve belgeye girmek, değişiklikleri oldukça işe yaramaz IMO ve muhtemelen imkansız.

Değişiklikleri belgeleme çabanızı bırakın .

Bunun yerine, şu anda neyin işe yarayıp yaramadığını belgelemeye başlayın . Gelecekte değişiklik yaparken bu dokümantasyonu güncel ve güncel tutun.

Kaynak kontrolünüz var mı?

Bundan nelerin değiştiğini çözebilir misin?

Öyleyse, yeni özellikler veya hata düzeltmeleri olsun, bunu iş değişiklikleriyle eşleştirebilirsiniz.

Eski bir geliştirici posta kutusunu yeniden canlandırmak mümkün mü? (bunun gizlilik kaygıları ile geçerli olup olmadığından emin değilim). Oradan trolleyerek elde edilecek birçok bilgi olabilir.

Her şey sırayla. Belgelerinizi nerede saklıyorsunuz? Henüz yapmadıysanız, bir wiki oluşturun. Dokuwiki'yi kendim tercih ediyorum ve eğer çok eğimliyseniz , önceden oluşturulmuş bir vm bile var .

Bu, bazı önemli özellikler sağlar:

• Dokümanlara şirket ağının herhangi bir yerinden erişilebilir (yeni bilgisayara yükleme ...)
• Tüm dokümanlar tek bir yerde
• Tüm dokümanlar aranabilir
• İşbirliği yapabilirsiniz (yeni iş arkadaşı, yazılım kullanıcıları)

Şimdi, belgeleriniz kağıt biçimindeyse, size en iyisini diliyorum. Word dokümanlarınız varsa, bir içe aktarma komut dosyası oluşturun .

Son olarak, sadece bir şeyler kullanın . Bir şey yüklemeniz gerektiğinde, wiki'ye notlar koyun. Bir kenar kasasına çarparsanız, wiki'ye koyun. İşbirliğinin parlayabileceği yer burası, çünkü başkalarının sizin için işi yapmasını sağlayın.

Daha spesifik belgelere geçmek için, çeşitli projeler için kaynakla çalışmanız gerekiyorsa, uygun bir geliştirme ortamının kurulduğundan emin olun ! Bir kontrol listesi için sahip olmanız gerekir:

• Sürüm kontrolü ( git , mercurial , fosil )
• Hata izleme ( trac , mantis , redmine , fosil )
• Yapı sistemi ( Autotools , scons , BuildBot'ın )
• Proje kontrolü ( tutulma , belirtilen dizin yapısı, editör eklentisi )
• Kaynak dokümantasyon (README, TODO, INSTALL, Kaynak yorumlar)

Son olarak, belgeler sıkıcı olabileceğinden, bir oyun yapın. Periyodik olarak "puanınızı" kontrol ederek, kontrol listenizdeki her bir öğe için kendinize "puan" verin. Neyi başardığınızı ve ne kadar iyi olduğunu görmenin iyi bir yolu. Ayrıca, bir sonraki adımda nereye gitmeniz gerektiğini de gösterir.

Buna, uygun bir geliştirme ortamının nasıl kurulacağı hakkında birçok şey öğrenme fırsatı olarak bakın ve bir şeyleri denemekten ve devam etmekten korkmayın. Beğendiğiniz bir şey bulun ve daha iyi olabilmek için çevreyi taşıyın . Buna en iyi çözümü oluşturmak istediğiniz bir proje olarak yaklaşın.

Düzenle:

Aşağıdaki teçhizatın yorumuna göre, yapılacak bir başka yararlı şey, kaynak kodunun diyagramlarını oluşturmaktır. Freecode bir şeylere sahiptir ve bu makalede popüler diller için bazı listeler bulunmaktadır.

Yapabileceğiniz en iyi şey, bildiğiniz her şeyi belgelemek ve başkalarının da bildiği her şeyi belgelemek için şirket etrafında sormaktır. Herkesin en güncel belgelere erişebilmesi için belgelerin bir wiki veya benzeri bir şekilde merkezileştirilmesini öneririm.

Bilmediğiniz bir şeyi belgeleyemezsiniz, bu yüzden ya bir şeyin neden yapıldığını öğrenmeye ve keşfetmeye çalışırsınız ya da belgesiz olarak bırakırsınız. Bu yüzden, şirketin hala işini bilenleri belgelemek için daha fazla özen göstermesi gerekiyor.

Anlamadığınız herhangi bir kodu belgelemeye çalışıyorsanız, işlevselliği test etmek için birim testleri yazmanızı öneririm. Bu şekilde, kodun ne yaptığını ve testlerin kendilerinin dokümantasyon olarak hizmet edebileceğini daha iyi anlayacaksınız.

İyi şanslar!

Artık projede veya şirkette olmayan birisinin yaptığı bir şeyi belgelemeye çalıştığımda her zaman şu tavrı benimsiyorum: Bir şeyi değiştirmem veya başka birine açıklamam gerekene kadar bu benim dahil herkese bir kara kutu.

Bu projenin bulduğunuz dokümantasyon şeklinde olmasının nedeni, herhangi bir çalışmanın dokümantasyonunun projenin çalıştırılmasında ikincil olmasıdır. Bu nedenle, neyi değiştirdiğinizi ve veritabanındaki belirli bir alanın ne olduğunu ve başka bir kod bloğunun ne yaptığını anladıysanız, başka birinin yararı için değilse, kendinizinkini belgeleyin.

Otomatik keşif testleri yazabilirsiniz. Bunların birkaç avantajı vardır:

• Siz yazarken sistemin nasıl çalıştığını öğrenirsiniz

• Daha sonra için yürütülebilir belgeler olarak hizmet ederler

• Bunları düzenli veya hatta sürekli olarak çalıştırırsanız, değişikliklerin ne zaman bir şeyi kırdığını veya ne zaman güncellenmeleri gerektiğini tespit etmek için güzel bir güvenlik ağı sağlarlar.

Yine de kendi ortamınıza bu tür testler yazmanın mümkün olup olmadığını bilmiyorum.