Zaten geliştirilen bir proje nasıl belgelenir?

Daha önce geliştirilen bir projeyi belgelemek için hangi seçeneklerin mevcut olduğunu bilmek istiyorum, çünkü üzerinde çalışan geliştiriciler tek bir sayfa belgesi bile yazmadılar.

Projenin, son 2 yıldır bu projede çalışan geliştiriciler tarafından yazılan ve değiştirilen işlevlere sahip birçok komut dosyası sayfası dışında başka bir ayrıntısı yoktur. Tüm sahip olduğum veritabanı şeması ve proje dosyaları. Gelecekte bu proje üzerinde çalışacak geliştiricilere yardımcı olması için bu projeyi organize etmenin ve belgelemenin herhangi bir yolu olup olmadığını bilmek istiyorum.

Proje PHP ve MySQL ile geliştirildi. Fonksiyonlar zayıf yorumlanmıştır, bu yüzden doxygen ile çalıştırdığımda iyi sonuçlar elde edemiyorum.

Belgeleri kim okuyacak? Belgeler ne için kullanılacak? Bunlar cevaplanması gereken en önemli sorular. Örneğin, bakım geliştiricileri için dokümantasyon daha çok yapıya odaklanırken, ürünle entegre olan geliştiriciler için dokümantasyon daha çok web hizmetleri ve veritabanı yapısına odaklanır.

Genel olarak, gerektiği kadar dokümantasyon yapın ve artık yok. Birçok kuruluş belgelere ihtiyaç duyar, çünkü birisi bunun en iyi uygulama olduğu konusunda ısrar eder, ancak belgeler toz toplar.

İnsanların belgeleri gerçekten kullanacaklarını varsayarsak, kodu ve veritabanını en küçük düzeye çekmeye çalışmayın. Geliştiriciler, minutiae koduna bakacaklar. Bunun yerine, kodda görünmeyen ayrıntılara odaklanın, örneğin:

1. Kullanım durumları ürün karşılamaktadır. Ürünün yaşı göz önüne alındığında bu zor olabilir, ancak ürünün ne yapması gerektiğini yakalamak, teknik olmayan okuyuculara ve test kullanıcılarına hayati bir bağlam sağlar. Pazardaki rakipler kimlerdir (varsa)? Ürünün kapsamı dışında bırakılan bir şey var mı?
2. Herhangi bir açık, işlevsel olmayan gereksinimler . Örneğin, ürün belirli bir cilt için yazıldı mı? Veriler kaç yaşında olabilir? Önbellek nerede kullanılır? Kullanıcılar nasıl doğrulanır? Erişim kontrolü nasıl çalışır?
3. Veritabanı, kimlik doğrulama kaynakları, yedekleme, izleme ve benzeri gibi diğer sistemlerle etkileşimi gösteren bir bağlam diyagramı .
4. (Biliniyorsa) Riskler ve bunların bir karar kaydı ile birlikte nasıl azaltıldığı . Bu, geçmişe bakıldığında muhtemelen zordur, ancak bir tasarımı etkileyen kritik kararlar vardır. Bildiğini yakala.
5. Ortak tasarım kalıpları veya tasarım yönergeleri . Örneğin, veritabanına erişmenin standart bir yolu var mı? Bir kodlama veya adlandırma standardı var mı?
6. Genellikle akış şemaları veya UML etkinliği veya sıra diyagramları kullanan kritik kod yolları . Projede herhangi bir bilgi olmayabilir ancak bunlar genellikle ticari kullanıcıların dile getirdiği konulardır.

Tüm bu bilgiler mevcut olmasa bile, şimdi başlayın . Sizden sonra gelen geliştiriciler size teşekkür edecektir.

İyi otomatik ünite testleri veya test senaryoları , daha az teknik personel için erişilmesi zor olsa da, yararlı belgeler olabilir.

Ayrıca , dokümantasyonu dahil etmek için kültürel bir değişiklik yapmanız gerektiği anlaşılıyor . Küçük başlayın ama ideal olarak, proje en az düzeyde bir dokümantasyona sahip olana kadar "yapılmamalıdır". Bu muhtemelen en zor adımdır çünkü yukarıdakiler kontrol edebileceğiniz şeylerdir. Bu, başkalarının satın alması gereken bir şey. Bununla birlikte, özellikle bir sonraki projeniz iyi belgelerle geliyorsa, en ödüllendirici olabilir.

Geçmişte, çeşitli ürün sahipleriyle veya güç kullanıcılarıyla oturarak, birincil kullanım durumlarını inceleyerek ve bunları bir dizi testle belgeleyerek böyle bir durumu yönettim. Gelecekte değişiklik yapmaya başladığınızda, bunları sistem için bir temel olarak kullanabilirsiniz. Bu aynı zamanda sistemin sahibi veya kullanım durumu olmayan ve muhtemelen silinebilecek alanların belirlenmesine yardımcı olabilir.

Her şey gerçekten sistemin boyutuna bağlıdır. Bu, birçok farklı paydaşa sahip karmaşık bir sistemse, hangi yeteneklerin var olduğunu ve nerede tatmin olduklarını ayrıntılı olarak anlatan üst düzey bir bileşen diyagramı oluşturabilirsiniz. Bu, sistem tasarımındaki mimari sorunları tanımlamak için çok yararlı olabilir.

Genel olarak eski moda dokümanlardan kaçınmayı öneriyorum, çünkü tarihi geçmiş olacak ve gelecekte geliştiricileri kaçıracak. Her zaman sistem geliştikçe sürdürülecek testler şeklinde canlı belgeler üretmeye çalışırım.

İlk önce, hedef kitleniz kim? Gelecekteki geliştiriciler mi yoksa diğer iş adamları mı? Bu sorunun cevabı akılda tutularak:

Diğerlerinin söylediği gibi, yüksek düzeyde bir açıklama ihtiyacınız olan ilk şeydir. Sistemin daha geniş bir şemada ne yapmaya çalıştığını açıklayın. Ne üzerinde çalıştığını, ağa nasıl uyduğunu ve diğer herhangi bir sistemle nasıl konuştuğunu açıklayın. Sonra her bir ekrandan geçer, ekran görüntüsünü alır ve ekranın ne yaptığını ve sistemin diğer bölümleriyle nasıl etkileşime girdiğini hızlıca açıklarım. Eğer geliştiriciler için ise, uygulamayı ilk kez onlara açıklıyormuşsunuz gibi konuşmaya devam edin. Sonuçta, bu doktorun noktası (sanırım).

Herhangi bir karmaşık işleme veya mantık bir durum diyagramı, veri akış diyagramı veya dizi diyagramı kullanırdım. Kesinlikle bir varlık diyagramı, daha sonra bir DB şema tasarımı yapın (iki farklı şey!). Belki temel bir sınıf diyagramı ama basit tutmak, sadece ilgi çekici ana şeyleri not edin, devs koda bakarak bu şeyleri anlayabilir.

Başlarken sorun yaşıyorsanız, hemen yanındaki odada başka bir geliştirici varmış gibi davranın, sistem hakkında ilk şeyi bilmeyen, nispeten sabırsızım ve sadece bunun özünü bilmem gerekiyor. Sonra açıklamaya başlayın ve söylediklerinizi yazın :)

Önceki önerilerin hepsi iyi, ancak kullanıcı topluluğunuzun kendilerine özel belgeler oluşturup oluşturmadığını da araştırmayı düşünürüm. Sorunuz, 'ürününüzün (iki yıldır var olan) herhangi bir sürümünün kullanıcılara yayınlanıp yayınlanmadığını belirtmedi. Kullanılıyorsa ve resmi bir belge yoksa, ya hiçbir belge gerekli değildir ya da temel olabilecek ancak muhtemelen kullanıcılar tarafından gerekli görülen bir yerde 'resmi olmayan' belgeler vardır. Web'de kritik API'leri temsil edecek, forumlarda arama yapabilir, ileri düzey kullanıcılara soru sorabilir ve soru cevap sitelerinde arama yapmayı deneyin. Mümkünse, teknik veya iş gereksinimlerini karşılayan belgeler yazmaya çalışın.

Soru şu ki, şimdi olduğu gibi veya olması gerektiği gibi belgelemek istiyor musunuz?

Sorunuzdan okuduğum şey, çok fazla kullanıcı belgesi değil, API belgeleri hakkında düşünüyorsunuz ve kod belki de çok iyi korunmuyor ve şifreli değil.

Korkarım şimdi belgelerseniz, kod yeniden düzenlendikten sonra işinizin çoğunu atmanız gerekir.

Aşağıdaki yaklaşımı benimserdim:

• ortak en iyi uygulamalara bağlı kalarak belgeleri mümkün olduğunca gereksiz hale getirin. Sezgisel olarak anlayabileceğiniz iyi sınıf adları, yöntem adları, değişken adları seçin
• büyük canavar sınıflarını ve / veya mantıklı olduğu işlevleri yıkmak
• PHPdoc yorumlarını kullanma - API belgeleri oluşturmak için araçlar kullanabilirsiniz
• Bunun için testler yazın: Testler, kodun ne yapması gerektiğini anlamanıza veya tanımlamanıza yardımcı olacaktır.

Şimdi, hala belgelenmemiş şeyleriniz var: bu genel kavramlar, mimari vb. Olabilir. Bunun için aslında belge yazardım - ama sadece gerçekten yararlı ve yararlı olanları yazın.