Bir tasarım belgesi, belirli bir tasarımın artılarını / eksilerini tartışmalı mı yoksa gerçeklere ve mantığa mı odaklanmalı?

Şu anda bir tasarım belgesini, gelecekteki geliştiriciler için doğru ve güncel olacak şekilde güncelleme sürecindeyim.

Şu anda, belge tasarımın nasıl olduğunu gösteren sadece gerçeklere odaklanmaktadır. Sunulan kararlar için herhangi bir gerekçe yoktur. Gerekçelerin yakalanmasının önemli olduğunu düşünüyorum, böylece geliştiriciler bir şeyin neden olduğu gibi olduğunu biliyorlar, çünkü bu muhtemelen gelecekteki kararları etkileyecektir. Tüm tasarım kararları için, özellikle de proje üzerinde çalışmaya başlamadan önce vermiş olduğum kararlara gerekçe eklemek mümkün değil, ama bu departmanda yapabileceğimi yapıyorum.

Bununla birlikte, bazı tasarım kararları saygıyla, projenin gereklilikleri göz önüne alındığında çok zayıf kararlardır. Yine de bazı iyi olanlar da var.

İlk düşüncem, gelecekteki bakıcıların dikkatini odaklamak için bu sorunlara tasarım sorunları ve potansiyel çözümler veya geçici çözümler hakkında bir tartışma eklemem gerektiğiydi, ancak tasarım belgesinin bu tür tartışma ve bilgi için bir yer olup olmadığından emin değilim. Diğer insanların bu sistem üzerinde çalıştığı ve belgeyi güncellediği için, açıkça uygunsuz olduğu için, bir tasarımın "eleştirisini" kartopuna "bu tasarımı yenisini" dönüştürmek istemiyorum.

Yöneticim her iki kararı da destekledi, bu yüzden bana kalmış. Hangi yaklaşımı benimsediğimden bağımsız olarak, üretilen belge resmi olarak sürümlendirilecek ve sistem üzerinde çalışan geliştiricilere, tipik olarak geliştirme çalışmaları ile görevlendirilmeden önce sağlanacaktır. Yeni bir geliştiricinin, geliştirme çalışmalarına başlamadan önce belirli bir yazılım sistemiyle ilişkili belgelere alışması beklenir.

Sorular:

• Bir tasarım belgesi ham gerçeklere ("tasarım bu") ve mantığa ("işte bu yüzden tasarım budur") bağlıysa veya tasarımla ilgili sorunlu olabilecek kusurlu sorunları belirtmek için de kullanılmalıdır gelecekteki geliştiriciler?
• Tasarım belgesi bu bilgiyi yakalamak için kullanılmazsa, ne tür bir belge onu yakalamalı ve tasarım rasyonları, ödünleşmeleri ve bilinen sorunlar (kusurlar izlendiği için kusur olmayanlar) tartışmasıyla başka ne yakalanmalıdır? diğer araçları kullanarak)?

Artıları ve eksileri bir veya iki cümlede özetlenebilirse, bunları bir tasarım belgesine koymak sorun olmaz. Daha uzun her şey ayrılmalıdır.

Şu anda çalıştığım yerde, genellikle tüm Büyük ve Önemli kararları izlemek için ayrı bir "Tasarım kararları" belgesi vardır. Genellikle sorunu açıklayan bir paragrafla biçimlendirilir (örneğin, "Bazı dosyaların her işlem döngüsünün sonunda bir sunucudan belirli kullanıcılara taşınması gerekir, bunu yapmanın birçok yolu vardır ..."), sütun içeren bir tablo " çözüm açıklaması "(" dosyaları FTP üzerinden taşı ")," artıları "(" Kullanıcıların yönetmesi kolay "gibi)," eksilerini "(" ABC-XYZ uyumluluğu için yeterince güvenli değil "gibi) ve Belirli bir kararın neden seçildiğini açıklar (örneğin, "belirli uyumluluk gereksinimlerini karşılayamayacağı için FTP kullanılmayacaktır" gibi). Tasarım belgesi genellikle sadece seçilen karara referans verir,

Bir tasarım belgesi ham gerçeklere ("tasarım bu") ve mantığa ("işte bu yüzden tasarım budur") bağlıysa veya tasarımla ilgili sorunlu olabilecek kusurlu sorunları belirtmek için de kullanılmalıdır gelecekteki geliştiriciler?

"Ya" ya da "değil.

İlk etapta hiç kimse belgeleri okumaz. Yağsızlar - en iyi ihtimalle. Bu nedenle, mümkün olduğunca az belge yazın. Tek bir belge herkesin sabrı var. "Diğer konular" içeren ikinci bir "tanımlanmamış" belgenin okunması pek olası değildir.

Bir belgenin avantajları? İnsanlar okuyabilir.

Bir belgenin dezavantajları? Az. Çoğunlukla güncel değil.

Birden fazla belgenin avantajları? Yok.

Birden çok belgenin dezavantajları? Lütfen KURU ilkesini ve okuryazar programlamayı okuyun. Birden çok belge, birden çok hata kaynağı anlamına gelir. Her belge diğerine katılmıyor ve koda katılmıyor. Bu oldukça açık. Bu delilik yoludur.

Elle sıkmaktan kaçının.

Artıları ve eksileri bir belge, ne olursa olsun ve çekici rahatsızlık tartışmalarının belirsiz derinliklerine sürüklenebilir.

Artılarını ve eksilerini sunmanın gerekli olduğunu düşünüyorsanız, kısa ve öz tutun.

Ne olduğuna odaklanın.

Çıplak kemiklere kadar olmayanı saklayın.

Kıyaslamalar, çalışmalar veya gerçekten araştırılmış alternatifler yaptıysanız, bunu belgeleyin. Ancak sadece alternatifleri düşünüyorsanız, en aza indirin.

Bu sizin kişisel yargılama ve sıkıntı tarihiniz olmamalıdır.

• Bir sorun mu var? Onu düzeltti? Haftalar mı sürdü? Gerçekten mi mücadele ettin? Ancak ilginç bir fıkra. Kodda düzeltildi. Önceki sürümler, yanlış sürümler, buggy sürümleri ve düşük performanslı sürümler önemli değil. En iyisi blog yemidir.

• Hala bir sorun mu var? Düzeltilmedi mi? Bu alternatifler olduğu anlamına gelir. Bunu belgeleyin.

Karar verme sürecinde 3 önemli gerçek vardır:

• Denenen ve işe yaramayan (neden işe yaramadı, çünkü hareketli bir hedefi hedefliyorsunuz)
• Nedir
• Ne olabilir (sadece X'in uygulanmasını bekliyor ...)

Bununla birlikte, "Nedir" dışında, diğerleri okuyucuyu karıştırır ve sistemi atlatmasını önler.

Diğer 2'yi yakalama fikrini seviyorum, sistemi öğrenmek için daha az ilginç olsalar da, değiştirirken zamandan tasarruf edebilirler.

Bu nedenle, bir bükülme ile @FrustratedWithFormsDesigner maruz fikri üzerine inşa ediyorum. Yine kendi başına bir yaşam döngüsü olan başka bir belge oluşturmak yerine, bir ek bölümü ele alacağım. Sonra tartışmaya değer her karar için, ekteki ilgili girişe işaret ederim.

Evet. Bir tasarım belgesi, tarif edilen tasarımla ilişkili faydaları, riskleri ve varsayımları açıklamalıdır. Bir tasarım belgesinin çeşitli amaçları vardır:

1. Tasarımı herkesin anlayabilmesi ve böylece her bireyin anlayışının zaman içinde kaymaması için yazılmasını sağlayın.

2. Tasarımı proje üzerinde çalışan teknik olmayan kişilere iletin.

3. Planlama, kaynak tahsisi, maliyet tahmini ve diğer planlama türlerine yardımcı olun.

4. Genel proje dokümantasyonunun önemli bir parçası haline gelir. Devam etmekte olan bir projeye katıldığınızda veya tamamlanmış bir projeyi sürdürmeniz gerektiğinde, iyi yazılmış bir tasarım belgesi varsa yaşam çok daha kolaydır.

5. Genellikle sözleşmenin gerektirdiği teslimat kalemlerinden biridir.

(Muhtemelen başkaları da vardır, ancak bunlar iyi bir başlangıçtır.)

Bu amaçların her birine, bu tasarımın neden seçildiğini ve ilişkili risklerin ne olduğunu açıkça açıklayan bir tasarım dokümanı tarafından iyi bir şekilde sunulmaktadır:

1. Ekipteki herkesin risklerin ve faydaların ne olduğunu bilmesi önemlidir, böylece bu risklerden kaçınmak ve tasarımın faydalarından en iyi şekilde yararlanmak için birlikte çalışabilirler.

2. Teknik olmayan ekip üyeleri için, riskleri ve faydaları anlamak genellikle tasarımın kendisinden daha önemlidir.

3. Risk yönetimi, bir proje yöneticisinin başarıyı sağlamak için yapabileceği en önemli şeylerden biridir ve ilk adım, yönetilmesi gereken riskleri tanımlamaktır. Risklerle nasıl başa çıkılacağına karar vermek bir yöneticiye bağlı olmalıdır, ancak tasarımın bilinen risklerini belirtmek tasarımcının sorumluluğundadır.

4. Bir risk artık sorun olmasa bile, belgenin belgelenmesi genellikle yararlıdır çünkü tasarımın oluşturulduğu andaki durumu açıklamaya yardımcı olabilir. Bu, bir bakıcının şöyle bir şeye karar vermesine izin verebilir: "Tamam, o zamanlar bu şekilde yaptılar çünkü ... ama bu artık bir sorun değil, bu yüzden bu kodu daha basit, daha hızlı bir uygulama ile değiştirebilirim." Aynı şey elbette faydalar için de geçerli.

5. Bir müşteri için bir proje üzerinde çalışıyorsanız, riskleri ve faydaları belgelemek özellikle önemlidir. Bu, müşteriye belirli koşullar altında işlerin yanlış gidebileceğini veya tasarımda değişiklik yapılmasının vaat edilen bazı faydaları tehlikeye atabileceğini fark eder.

Zaten uygulanmış bir sistem için var olan bir tasarım belgesiyle çalıştığınızı soruyorum. Bu durumda, olası risklerin birçoğu artık risk değildir, bu yüzden gerçeklerden sonra bunları belgelemeye çalışmak pek mantıklı değildir. Bununla birlikte, orijinal tasarımın çok iyi çalışmayan kısımlarını görebileceğiniz için artık arka görüş avantajına sahipsiniz. Bence ya: mevcut sorunlu alanları tanımlayan ve çözümler öneren ayrı bir bölüm ekleyin (ilişkili riskler dahil!); veya aynı şeyi yapan ayrı bir belge oluşturabilirsiniz. Bu yeni bölüm / belge, yazılımın bir sonraki sürümü için tasarım belgesine dönüşebilir.

Yararlı bulabileceğiniz tasarım belgeleri yazma üzerine bir blog girişi .

Daha açık veya standart çözümlerden kaçınmanın geçerli nedenleri varsa, bunlar not edilmelidir. Birini çok beladan kurtaracaksın. Bununla birlikte, belirli bir teknoloji zamanla gelişebilir, bu nedenle nedenleriniz geçerli olmayabilir. Gelecekteki bir geliştirici daha sonra kendi kararlarını kullanabilir.

Tüm kısa gelişmeleri işaret etmenin çok faydası olup olmadığını bilmiyorum. Değişikliklerin yapılması veya diğer önceliklerin yerine getirilmesi pratik olmayabilir. Bazılarını yakın gelecekte düzeltebilirsiniz ve bu güncellenmesi gereken bir şey daha olacaktır.

Şahsen bunu tasarım belgesine koymam. Bir tasarım belgesi neden olduğunu değil, nasıl olduğunu özetlemelidir.

Tasarımın neden böyle olduğuna dair bir hikayeye iyi bir ihtiyaç olduğunu düşünüyorsanız, belki de bunu bir wiki makalesine (veya şirketinizin kullandığı her türlü bilgi tabanına) koymalısınız, böylece tasarımın evrimi. Kullanıcılar gidip okuyabilir, düzenleyebilir ve öneriler ekleyebilir. Bu şekilde, bir belgede atılan kaş yerine açık bir tartışma yapılır.

Tasarım belgesine gerekçe koyma konusunda size katılıyorum.

Neyse,

başkası tarafından yazılmış bir tasarım belgesinin güncellenmesi sürecinde, mütevazi kalacağım ve bu kararın neden alındığını tahmin etmeye çalışmam.

Yani,

Sadece bakım sırasında tasarımda yapılan değişiklikler hakkında mantık eklerdim.