Ürün tasarım kararlarının arkasındaki gerekçeleri kaydetmenin etkili bir yolu nedir?


30

Şirketimizde ürün tasarım belgelerini kullanmıyoruz. Toplam üç çalışanımız var, bu nedenle tüm ürün tasarımı tartışması şahsen veya Slack'de gerçekleşiyor. (Ayrıca yalnızca en yeni mesajları görüntülemenizi sağlayan temel Slack paketindeyiz.)

Ürünümüz hala erken aşamada ve aylar önce karar verilen tasarım öğelerini tekrar ziyaret ediyoruz.

Sık sık sıkça karşılaştığımız bir sorun, ürün tasarım kararının neden verildiğini unutmak. Bu, aynı zeminin tekrar kaplanmasının harcanan saatlerle sonuçlanır.

Tasarım kararlarının arkasındaki gerekçeleri etkili bir şekilde nasıl kaydedebiliriz?

İş akışımız Pivotal İzleyici'ye dayanıyor. Aklıma gelen bir çözüm, ilgili tüm tasarım kararlarının gerekçelerini, kullanıcı hikayesi hakkında yorum olarak kaydetmektir, ancak bu güvenilmez görünüyor.

% 100 açık olması: Kodun tasarımından bahsetmiyorum. Kod ile gerçekleştirilen ürünün tasarımı hakkında konuşuyorum. Başka bir deyişle, "Bu sınıfı çoklu mirastan ziyade kompozisyon kullanarak mı yapmalıyız?" Gibi kararlardan bahsetmiyorum; "Oturum açmadan önce bir kullanıcının e-posta adresini onaylamasını ister miyiz?" Gibi kararlardan bahsediyorum.

Dokümantasyonun amacı, işletmenin kararların neden alındığına dair bir kaydı görmesine, aynı konular hakkında daha fazla karar vermesine yardımcı olmaktır.


13
Bir tasarım belgesine ihtiyacınız olduğunu düşünüyorsanız, neden sadece bir tasarım belgesi oluşturmuyorsunuz?
MetaFight

Sanırım rasyonellerin ilk tahminde, nesir, yazılı nesir olarak kaydedileceğini sanıyorum. Bunun için amaçlanan okuyucu kim?
Laurent LA RIZZA 22:16

Neden bunu Pivotal'daki kullanıcı hikayelerine kaydetmenin güvenilir olmadığını söylüyorsunuz? Bu yazılımı hiç kullanmadım, ancak normalde bir bilet, bileti yükseltme motivasyonunu kaydetmek için iyi bir yerdir. Sadece "E-posta adresini onaylamak için kullanıcı iste" yazmayın, "E-posta adresini onaylamak için kullanıcı iste. Bu yardımcı olur ..." ifadesini girmenizin güvenilmez olduğunu mu söylüyorsunuz? (doğru şeyi yapman için), veya güvenilmez çünkü eski Pivotal hikayeleri karadelikten kaybolur ve onları bulamazsın, yoksa başka bir problem mi var?
Steve Jessop,

Yazarlar kimler ve bu belgelerin tüketicileri kimler? Bana "iş" yazarı gibi geliyor ve herkes bunun okuyucusudur? Bu doğru olur mu? (Şu an küçük olduğunuza inanıyorum, ama büyümek olsaydınız cevaplar ne olurdu?)
mlk

"Oturum açmadan önce bir kullanıcının e-posta adresini doğrulaması gerekiyor mu?" Bu tür kararlar kabul kriterleri altına girmelidir.
kumards,

Yanıtlar:


26

Tasarım kararlarının arkasındaki gerekçeleri not alarak kaydedersiniz. İdeal olarak, karara bağlı öğenin yakınında (bir "kullanıcı hikayesi" değildir - kullanıcı hikayeleri, nasıl uygulanmalı, ne yapılması gerektiği değil).

Yani neyi özellikle olduğunu comments kayda - için yapılmış niçin öyle gibi kod veya yapı görünüyor belirli bir parçasının (ve kod yorumların münhasıran söz etmiyorum). Tasarımınızın konusu bir işlevse, işleve giriş niteliğinde bir yorum yapın. Bir sınıfsa, bir sınıfın başında gerekçeyle ilgili bir yorum yapın. Aynı yapıyı izlemesi gereken bir sürü sınıfa sahipseniz, bu sınıfları içeren pakete ayrı bir tasarım dökümanı (bir "readme" dosyası gibi) ekleyin. Tasarımınızın konusu bir UML diyagramıysa, şemanın açıklama bölümüne yorumlar ekleyin.

IMHO tasarım dokümanları kendi değerlerine sahip olabilir, ancak tanımladıkları öğeden "çok uzak" şeyleri açıklarlarsa, çok hızlı bir şekilde tutarsız olma eğilimindedirler. Bu yüzden benim önerim, herhangi bir tasarım belgesini, tasarlanan öğeye mümkün olduğunca yakın koymaktır.

Ayrı belgeleri yalnızca, kodunuzun birçok yerini etkileyici bir şekilde etkileyen tasarım kararlarını belgelemek istediğinizde kullanın. Bunları kullandığınızda, onları kod tabanınızın bir parçası haline getirmeye çalışın ve bunları tasarlanan konunun hiyerarşi seviyesine yerleştirin (bu nedenle, birçok kaynak kod dosyasından oluşan bir modül için bir tasarım kararı verirseniz, tasarım açıklamasını yerleştirin " içinde "bu modül, ancak bir sınıf dosyasında değil, diğer modüller için geçerli olan bir" üst seviye tanımlamaya "değil, kesinlikle SCCS'nizin dışında kesinlikle ayrı bir Wiki'ye yazılmamış. geniş tasarım kararları, daha sonra en üst düzey bir belge belki de en iyi yer, ancak bu belgenin o soyutlama düzeyinde kaldığından emin olun.


Yorumlar hakkında: Yorumların amacının kod tanımlamak olduğunu söylemiyor musunuz? Çünkü, bahsettiğim tür sorun tasarım sorunları, çünkü: kullanıcının Y hesabı ayarları verilen X izinleri olmalı mı? Kodun amacı tasarımı mümkün kılmak, bu yüzden tasarımı tartışmak için uygun yerin kodda olduğunu sanmıyorum.
henrebotha

5
@ henrebotha: Tasarımın ne olduğu, olması gerektiği veya olması gerektiği hakkında benden farklı bir fikriniz var. Kod tasarımdır. Kodun yapısı tasarımdır. Kullanıcı arayüzlerinin yapısı tasarımdır. Kod veya sınıfların meta yapıları tasarımdır. "Kullanıcının Y hesabı ayarları verilmiş X izinleri olması gerekiyorsa" gibi bir soru bana yazılımınızın herhangi bir yerinde yerleştirilmesini istemediğiniz bir şey gibi geliyor - yapılandırılabilir bir gereksinim gibi geliyor. Bu gereklilikleri kodda nasıl uygularsanız, belki de bir tasarım kararı olabilir, böylece kodunuzda bir yere yorum yapabilirsiniz.
Doktor Brown,

2
@ henrebotha: Eğer X hesap ayarlarını Y hesaplamasına izin verirseniz, kod bu karardan etkilenecektir. Bazı izinleri denetleyen kod, bazı hesap ayarlarını yöneten kod, bazı kullanıcı arabirimi kodu, bazı denetleyici kodu. Bu nedenle, tüm bu yerlerde kodda bir yorum yapılmalıdır. Elbette, tekrarlamalardan kaçınmak için, tüm yorumlar ayrı bir tasarım belgesine atıfta bulunabilir, eğer arkasında birçok farklı yeri etkileyen bir mantık varsa (
Doc Brown

1
Tasarım kararlarının kodu etkilediğine itiraz ediyorum. Elbette tasarım kararları kodu etkiler. Bu yine de, ürün tasarım kararlarını kaydetmek için yorumların doğru yer olduğu anlamına gelmez.
henrebotha

1
@ henrebotha: "Ürün tasarım kararları" ile neyi kastediyorsunuz? "Ürün çapında" tasarım kararları, ürün belgelerinizin "üst düzey" kısmındaki bir belgeye ait olabilir. Herhangi bir "ürününüzün içindeki tasarım kararları" nı kastediyorsanız, bazıları kod yorumlarına aittir, bazıları değildir. Ancak sadece kod yorumlarından bahsetmiyorum, düzenlememe bakın. Kod tabanınıza dahil ettiğiniz herhangi bir yorumdan (kod içinde veya ayrı belgelerde) bahsediyorum.
Doc Brown,

8

Çevik bir yaklaşım düşünün. Yani, gerekçelerinizle birlikte verdiğiniz her tasarım kararını yazmak için zaman kaynaklarınız ve mükemmel yazma beceriniz varsa, her şeyi belgeleyin. Gerçekçi konuşursak, sanırım böyle bir durumda değilsin. Çevik bir yaklaşım, gerekçelerin belgelenmesi için önemli bir zorluğa yardımcı olabilir: çoğu zaman hangi gerekçelerin önemli olduğunu bilmiyorsunuz.

Soruna bütünsel bir bakış açısıyla yaklaşalım. Siz kararınız için gerekçeleriniz var. Şu an squishyware içinde kalmışlar, takımın beyni. Kredi belgelerinin miktarına rağmen, rasyonelleri sqishyware'de depolamak o kadar da kötü değil. Aslında önemli şeyleri hatırlamakta bir tür olarak gerçekten iyiyiz . Her büyük şirketin neden bu aşiret bilgisini belgelemeye çalışsalar bile, "kabile bilgisine" sahip olmasının nedeni budur.

Şimdi bir problemin var. Sqiushyware'in gerekçeleri yeterince iyi tutmuyor olduğunu görüyorsunuz. Bir sorun olduğunu fark ettiğiniz ve çözülmesi gerektiğini belirlediğiniz için iyi bir şey! Bu her zaman kolay bir adım değil! Bu yüzden, çözümün bu mantığın bir kısmını dokümantasyona boşaltmak olduğundan eminiz. Ancak, bu yeterli değil. Bir karar vermeniz gerektiğinde gerekçeyi squishyware'e yeniden yükleyen bulmacanın ikinci yarısını asla unutamayız. Delice gibi her şeyi belgeleyen çok sayıda ekip gördüm, ancak içerik aslında iyi kararlar almak için organize değil, bu yüzden yazılsalar bile gerekçeleri unutuyorlar .

Demek iki aşamalı bir sürecin var. Gerekçeyi squishyware'den ve dokümantasyondan çıkarmanız gerekir. Öyleyse, gerek duyduğunuzda rasyonel olarak squishyware'i geri getirebilecek kadar iyi organize edildiğinden emin olmalısınız! Şimdi, zorlukların nerden hoşlanacağını anlamak için yeterince problemli bir ifademiz olduğunu düşünüyorum. Belgeleme yaparken, genellikle kimin daha sonra bakacağını ya da ne aradıklarını bilmiyorsunuzdur. Aynı şekilde, belgelere tekrar bakarken, genellikle ne aradığınızı bilmiyorsunuz (en iyi ne zaman bildiğinizi).

Yani büyük bir şirket bunu iki büyük blokta ele almaya çalışabilir. İlk önce, insanların belgeleri araştırırken neye ihtiyaç duyduklarına dayanarak gereksinimler geliştirebilirler. Ardından, söz konusu dokümantasyonu geliştirmek için bir süreç oluşturmak için bu gereksinimleri kullanırlar. Ve söylemeye cesaret edersem, o zaman herkes şikayet eder, çünkü neredeyse hiç kimse tam olarak hangi belgelerin ilk gün nasıl görünmesi gerektiğini bilmiyor . Belgeler her zaman eksiktir ve geliştiriciler her zaman sürecin çok ağır olduğundan şikayet eder.

Çevik olma zamanı.

Tavsiyem, dokümantasyon sürecinizi iyileştirmek için çevik bir çaba başlatmak olacaktır: squishyware'den belgeye ve squishyware'e geri dokuz metre. İşleminizi mükemmel olmadığı için bazı bilgileri kaybedeceğinizi kabul edin, çünkü bu işlem tamamdır, çünkü hala süreci anlamaya çalışıyorsunuz! Tüm çözümlere uyan tek bir beden oluşturmaya kalkarsanız daha fazlasını özlersiniz.

Bazı özel haberlere bakarım: * Gayri resmi belgeleri keşfedin. Resmi belgeler harika, ancak zaman alıcı. Dokümantasyonun amaçlarından biri, geliştirici squishyware bilgisini serbest bırakmak ve kağıda koymaktır. Gayri resmi belgeler bunu yapmanın maliyetini minimumda tutar.

  • Güvenilir olmayan dokümantasyon biçimlerini kabul edin. Hiçbir şey ilk kez doğru olmayacak. Veriyi almak ve daha sonra nasıl güvenilir hale getirileceğini bulmak daha iyidir. Örneğin, gerekçelerinizi bir <rationale> </rationale> bloğunda veya benzer bir şeyle belgeleyebilirsiniz; bu, daha sonra bu verilerin toplanmasını kolaylaştıracaktır. Gerekçeleri bir kullanıcı hikayesinde saklamak, şimdilik, sorun değil!
  • Organizasyonun değerini asla unutma. Bir ekip olarak, dokümantasyondaki rasyonelleri nasıl aradığınızı öğrenin ve bunu belgelemeye çalışın. Her takımın farklı bir süreci olacak. Ekiplerimden birinde, üzerinde mantıklı olan bileti hemen bulamadık. Yapabileceğimiz şey, önemli olan bir kod satırı svn blamebulmak, ne zaman değiştiğini ve nedenini bulmak için bir şeyler yapmak ve ardından biletlere bakmak. Bir zamanlar oradaydık, genelde tam da ihtiyacımız olan mantığı bilete koyduk. Bu sadece bizim için çalıştı, sizin için neyin işe yaradığını öğrenin.
  • Organik belgeler zamanla büyüyebilir. Geliştiricilerin yazmak için ihtiyaç duydukları gün hangi gerekçelerin en önemli olduğunu bilmeleri nadirdir. Genellikle hangilerinin önemli olduğunu bulduk. Geliştiricilerin kendi küçük gerekçeler bahçesini yönetmelerine izin veren belgeler için bir tımar işleminiz varsa, önemli olanlar yüzeye çıkacaktır. Daha da önemlisi, gerekçeler değişebilir. İki farklı mantığa sahip iki farklı değişimin, her ikisi için de işe yarayan tek bir mantık tarafından gerçekten en iyi şekilde tanımlandığını fark edebilirsiniz. Artık kararlarla aranızda daha az içerik var!

0

Özel bir MediaWiki örneği veya benzer bir wiki yazılımı kurmanızı öneririm. İçeriği orada düzenlemek ve yeniden düzenlemek gerçekten kolaydır ve yeni tartışmaları doğrudan ilgili wiki makalelerinin tartışma sekmesine kopyalayıp yapıştırabilirsiniz. MediaWiki'yi son işimde tüm mimarimiz ve API belgelerimiz için kullandık ve bu bir cankurtarandı.


2
Mimari ve üst düzey kararlar - tamam olabilir. API belgeleri - NO! Kuruluşumuzdaki bazı insanlar bunu geçmişte denedi ve her zaman aynı - düşük seviyeli dokümanlar kodla senkronize edilmedi. Wiki'ler VCS ile iyi bir şekilde etkileşime girmiyor, insanlar unutuyor veya güncelleme için zaman ayırmıyorlar. API belgeleri tanımladıkları işlevlerin önünde koda ait . İntranetinizde onlara ihtiyacınız olduğunu düşünüyorsanız, oradan çıkarmak için doxygen gibi bir HTML oluşturucu kullanın. Fakat kendinize bir iyilik yapın ve Wiki'de ayrı ayrı, manuel olarak saklamayın.
Doktor Brown,

3
Tüm tasarım gerekçelerinin kaynak kod deposuna yazılması gerektiğine inanıyorum. Başka herhangi bir yer var ve sadece senkronizasyondan çıkmıyorlar, aynı zamanda tarihlerini de hatırlamıyorlar.
cmaster

Çalışan bir çözümü küçümsemek ... Vay. Tamam ozaman.
Sıfır bant genişliği

0

12 ay içinde değiştirmesi istenen kodlayıcı açısından bunu düşünün.

Bu işletme kuralını otomatik bir test olarak eklerseniz, değişiklik yapılır ve sonra başarısız testten çıkacak olan çelişkili gereksinimi alırsınız (ve umarım orijinal gereksinimle ilgili kişiyi ve belirleme nedenini yakalarsınız).

Tasarım dokümanını (BPMN diyagramlarını, İşlem diyagramlarını, hatta beyaz tahtanın fotoğrafını vb. Koyduğunuz yer) koda benzeyen, sadece çalıştırılamayan bir form ... olarak kabul ediyorum ... Kayıt, bir kod yorumuna benzer, ancak tasarımda önceden belirtilen (test edilebilir) bir gereksinimdir. Muhtemelen çevik bir dükkansanız hala kodunuzu tasarlarsınız, yazmadan önce en son dakikada onu yaparsınız. Bunu, tüm diğer proje belgeleriyle birlikte kod tabanında tutunuz.

Ne yaparsanız yapın, aranabilir bir şekilde saklandığından emin olun (örneğin, yeni değişiklikler belirlerken "kimlik doğrulama" ile ilgili tüm işletme kurallarını kaldırmak isteyebilirsiniz).


0

Her zamanki gibi bir şeyler yazarken, hedef kitlenin kim olduğunu kendinize sormalısınız. Tasarım belgelerinin akran geliştiricilerim için, şimdiki veya gelecekteki olanlar için olduğuna inanıyorum. Belge, neyi inşa ettiğimi veya neyin inşa edildiğini anlamalarına yardımcı oluyor (yüksek seviyeli genel bakış) ve daha da önemlisi neden. Düşündüğünüz alternatifleri, her birinin artılarını ve eksilerini belgelemek için bir yer.

Bazı tasarımların insanların beyninde yaşamalarının tamam olduğunu söyleyerek, geliştiricilerin devam etmeleri ve farklı işler bulmaları, onlarla birlikte bu değerli bilgiyi almaları önlenir.

Kodunuzu tek tasarım belgeleri olması, bir büyüteç kullanarak şehir içinde yolunuzu bulmak gibi. Bir harita çok daha kullanışlıdır (maalesef kaynak kodu için GPS eşdeğeri yoktur).

Tasarım dokümantasyonunun kodlardan daha hızlı rotasyonda olduğunu kabul ediyorum. Ve ikisi arasında bir onaylama mümkün olmadığından, yapabileceğiniz tek şey onları yakın tutmaktır. Tarihsel bir tasarım belgesi olan IMO, hala değerli bilgiler sunmaktadır.

Sitemizi kullandığınızda şunları okuyup anladığınızı kabul etmiş olursunuz: Çerez Politikası ve Gizlilik Politikası.
Licensed under cc by-sa 3.0 with attribution required.