Sektördeki belgelere olan ilginin nesi var?

En temel belgelerin bile yazılmasının önlenmesi gibi görünüyor. Projemiz README'ler nispeten çıplak. Dokümanlardaki güncellenmiş bağımlılık listeleri bile yok.

Sektörde bilmediğim, programcıların dokümantasyon yazmayı sevmediği bir şey var mı? Gerekirse, dokümanların paragraflarını yazabilirim, öyleyse neden diğerleri bu kadar farklı?

Daha da önemlisi, onları belge yazma işleminin bize zamandan ve sıkıntıdan kurtulacağı konusunda nasıl ikna edebilirim?

Bence iyi bir uygulama olmadığını düşündüğünüz veya kötü bir uygulama olarak gördüğünüz bir şeyi yapmaya devam eden insanların motivasyonları üzerine spekülasyon yapmak faydalı olmaz. Bu işte, bu kategorilerden birine ya da ikisine birden giren insanlar, gözle göreceklerini çok daha fazla yaşayacak , bu yüzden kendini delirtmeyi bırak.

Bunun yerine, probleme ve olası çözümlere odaklanın.

1. İyi Belgeleri Kendiniz Yazın

Takımınızdaki herkesin çabalarını bir sorun olarak gördüğünüz şeylere yönlendirmesini beklemek gerçekçi olmayabilir. Bu, özellikle ekibin göreceli olarak yeni iseniz, geçerlidir. Olduğunu tahmin etmeye teşebbüs ediyorum, çünkü ekibin kurucu üyesi olsaydın, bu konuyu daha önce çözmüş olmalısın.

Bunun yerine, iyi belgeleri kendiniz yazmak ve insanların kullanmasını sağlamak amacıyla çalışın. Örneğin, ekibimden biri bana Proje A kaynak kodunun nerede olduğunu veya Proje A'nın hangi özel yapılandırmaya ihtiyaç duyduğunu sorarsa, onları Proje A wiki sayfasına yönlendiririm.

Birisi bana Müşteri C için bir şeyi özelleştirmek üzere nasıl yeni bir Fabrika F uygulaması yazacağımı sorarsa, bunun geliştirici kılavuzunun 10. sayfasında olduğunu söylüyorum.

Geliştiricilerin çoğu, belgeleri okumaktan nefret ettiklerinden daha fazla "kodu okuyamayacaklar" gibi görünmelerini sağlayacak sorular sormaktan nefret ediyorlar, bu nedenle bu nitelikteki yeterli cevapların ardından ilk önce doktora gidecekler.

2. Belgelerinizin Değerini Kanıtlayın

Belgelerin değerini kanıtladığını (veya kullanılıyorsa) sahip olacağınızı belirtmek için her fırsatı değerlendirdiğinizden emin olun. İnce olmaya çalışın ve "Size söylemiştim" den kaçının ama gibi şeyler söylemek tamamen meşru

Gelecekte başvurmak üzere, bu projenin wiki sayfası, 2.1 sürümünün devam eden desteği için oluşturulan ana kodun dalı hakkında bilgiler içerir, bu nedenle gelecekte sürümleri koruyan kişiler kontrol ederse tam bir regresyon testi yapmaktan kaçınabiliriz Kodu kontrol etmeden önce wiki.

veya

Görev T'yi yapma adımlarını yazdığım için çok mutluyum, başka hiç kimsenin kullanmamasını umursamıyorum - bu bana zaten harcadığımdan daha fazla zaman kazandırdı.

3. Gemide Yönetim Alın

Belgelere sahip olmanın zamandan / paradan tasarruf sağladığı birkaç olaydan sonra, muhtemelen belgelere yönelik belirgin bir "çözülme" fark edeceksiniz. Bu, tahminlerinize dokümantasyon süresini dahil etmeye başlamanın ne kadar önemli olduğunu söyleme zamanıdır (dürüst olmak gerekirse, derlemeler veya check-in işlemleri gibi uzun süreçler sürerken genellikle dokümanları güncellerim / oluştururum). Özellikle eğer bu yeni bir işe alım ise, bu sorgulanmayabilir, bunun yerine önceki bir işyerinden getireceğiniz yeni bir uygulama olarak görülüyor (ki bu olabilir).

Dikkatli söz: Çoğu patron , insanların bir şey yapmasını istemez , özellikle doğrudan faturalandırılabilir bir göreve bağlı olmayan şeyler, bu yüzden bu desteğin bir görev biçiminde olmasını beklemeyin. Bunun yerine, size daha fazla belge yazmak için nispeten özgür dizginleme yapma olasılığı daha yüksektir.

4. Gördüğünüzde Belgeleri Teşvik Edin

Belki de insanların dokümanları gerektiği kadar sık ​​yazmamasının bir parçası da kimsenin okumadığını hissetmeleridir. Bu nedenle, hoşunuza giden bir şey gördüğünüzde, en azından müsait olduğuna sevindiğinizden emin olun.

Ekibiniz kod incelemeleri yaparsa, bu, iyi yorumları teşvik etmek için ince bir kelimeye veya iki kelimeye bırakabileceğiniz bir zamandır.

Framework G'deki B böceği için geçici çözümü belgelendiğiniz için teşekkür ederim. Bunu bilmiyordum ve orada onsuz ne yaptığınızı anlamadığımı sanmıyorum.

Takımda dokümantasyon konusunda gerçekten hevesli biri varsa , o kişiyi öğle yemeğine ya da kahveye gidip ekibin geri kalanını görmekten alıkoyamayacak kadar küçük bir onaylama önerisi vererek yetiştirmek zarar vermez dokümantasyon kadar değer vermiyor.

Bunun ötesinde, liderlik ya da yönetim pozisyonunda olmadığınız sürece, bu gerçekten sorun değil. Bir atı suya götürebilirsin, ama içmesini sağlayamazsın. Eğer senin atın değilse, susadığı için mutlu olmayabilirsin, ama tek yapabileceğin yalakları doldurmak.

Tecrübelerimin iki ana faktörü var:

Tarihler

Çoğu şirket, QA, teknoloji borcu ve gerçek tasarımın sadece proje yöneticisinin kötü görünmemesi veya saçma vadesi vaat eden müşteri teslim tarihine çarpması için kesinti göstermesi için kesin tarih atıyor. İşlevsel kalitenin bile kesildiği bu ortamda, dokümantasyon gibi uzun vadeli bir yatırım çok az şansa sahiptir.

Değişiklik

Geliştiriciler için nispeten yeni bir en iyi uygulama, yorumları vurgulamaktır. Buradaki fikir, bilgiyi iki yerde tutmanın (kod [testler dahil] ve kodun etrafındaki yorumların) az bir fayda için senkronize olmaları konusunda çok fazla masrafa yol açmasıdır. "Kodunuz, yorum yapmanız gerektiğini okumak için çok zorsa, kodu temizlemek için zaman harcamak daha iyi olmaz mıydı?"

Şahsen artık yorumlara bile bakmayacağım. Kod yalan söyleyemez.

Belgeler aynı damarı takip ediyor. Çeviklerin yaygın olarak benimsenmesiyle, insanlar gereksinimlerin düzenli olarak değiştiğini kabul eder. Yeniden yapılanmanın yaygın olarak kullanılmasıyla, kodun organizasyonu büyük ölçüde değişecektir. Neden zamanını değiştirmek zorunda kalan tüm bu şeyleri belgelemekle geçiriyorsun? Kod ve testler bunu yaparken yeterince iyi bir iş yapmalıdır.

Burada oyunda bazı faktörler var:

1. İyi yazılmış bir kod kendi belgeleridir. Diğer tüm şeylerin eşit olması, daha fazla dokümantasyon yerine, kendisi için konuşan daha net bir kod yazmak daha iyidir. Bunu yapın; bu kodu değiştirdiğinizde daha az belge değiştirmeniz gerekecektir.

2. Dökümantasyon yazmak kesinlikle kod yazmaktan farklı bir beceridir. Bazı yazılım geliştiriciler bu konuda diğerlerinden daha iyidir. Bazıları kod yazarken dokümantasyon yazdıklarından çok daha iyidir.

3. Dokümantasyonun sadece bir kez yazılması gerekir , iki defa değil (bir kez kaynak kodunda ve yine programcının kılavuzunda). Bu nedenle XML yorumları ve dokümantasyon üreticileri gibi şeylere sahibiz. Ne yazık ki, bu tür araçları kullanmak, dokümantasyonu elle yazmaktan daha zor ve zahmetli olabilir, bu yüzden bu araçları yaygın olarak kullanmıyorsunuz.

4. İyi belgeler zaman alıcıdır ve iyi yapmak zordur. Diğer tüm şeylerin eşit olması, yeni kod yazmanın zaten var olan kodun belgelerini yazmanın dışında bir değeri olabilir.

5. Kod değiştiğinde, belgeleri de değiştirmeniz gerekir. Ne kadar az dokümantasyon olursa o kadar az değişmesi gerekir.

6. Kimse belgeleri okumuyor, peki neden rahatsız ediyorsun?

Odadaki Fil: Programcılar (mutlaka) yazar değildir. Ayrıca uygulamalarını teknik yazarlara aktarmaya da uygun değillerdir. Odadaki İkinci Fil: Teknik yazarlar genellikle gelecekteki geliştiriciler için yararlı olan ayrıntıları çözemezler (geliştiriciler bunları açıklamaktan caydırsa bile).

Karmaşık bir sistem, uygun dokümantasyon olmadan zamanla yaklaşılmaz hale gelebilir. Kod, temizlenebilirliği ile ters orantılı olarak daha az değerli hale gelir [sic]. Çözümlenen yönetim, geliştiricilerin kod ve koaksiyel ayrıntılarını okuyabilen, geliştirici oranında ona ödeme yapan ve belgelemeye ve dokümantasyonu sürdürmeye zorunlu kılan Yazılım Mühendisini işe alır. Bu yazar kodu okuyabilir ve hangi soruları soracağını bilir ve gerektiğinde ayrıntıları doldurur. Tıpkı bir QA departmanınız olduğu gibi, dahili bir dokümantasyon departmanınız da var.

Kod, üçüncü bir tarafa lisans verebileceğinizden daha değerli hale gelecektir (çünkü anlayabildiği için), kod daha kolay denetlenebilir ve geliştirilebilir / yeniden faktörlendirilebilir, kolayca kullanabileceğiniz yerlerde bile daha iyi bir kod kullanımına sahip olacaksınız. Yazılımınızın daha hafif sürümlerini hesaba katabilirsiniz ve yeni geliştiricileri projeye daha kolay bir şekilde tanıtabileceksiniz, destek mühendisleriniz sizin için çalışmayı sevecektir.

Bu asla olmayacak.

Daha da önemlisi, onları belge yazma işleminin bize zamandan ve sıkıntıdan kurtulacağı konusunda nasıl ikna edebilirim?

Bunu yapar mı?

İki tür dokümantasyon vardır:

Yararlı belgeler

Bitmiş bir ürünün, bir API'nin, sunucularımızın sahip olduğu IP adreslerinin veya URL'lerin nasıl kullanılacağını, vb. Nasıl kullanılacağını belgeler. Temel olarak, yoğun ve günlük olarak kullanılan her şeyi. Yanlış bilgi hızlı bir şekilde bulunacak ve düzeltilecektir. Düzenlenmesi kolay ve kolay bulunması gerekir (örn. Çevrimiçi Wiki).

İşe yaramaz belgeler

Sık sık değişen, çok az sayıda insan bununla ilgileniyor ve kimse onu nerede bulacağını bilmiyor. Uygulanan bir özelliğin mevcut durumu gibi. Veya 3 yıl önce güncellendi, SVN'de bir yere gizlenmiş bir kelime belgesindeki gereksinim belgeleri. Bu belgelerin yazılması ve sonradan yanlış olduğunu anlamak için zaman harcayacağız. Bu tür belgelere güvenemezsiniz. İşe yaramaz. Zaman harcıyor.

Programcılar işe yaramaz belgeler yazmaktan veya okumaktan hoşlanmazlar. Ancak onlara yararlı olan belgeleri gösterebilirseniz, yazacaklar. Son projemde sıkça ihtiyacımız olan tüm bilgileri yazabileceğimiz bir Wiki'yi tanıtırken büyük başarı elde ettik.

Asıl nedenin irade eksikliği ve belgelerin işlevini anlama eksikliği olduğunu söyleyebilirim. Göz önünde bulundurulması gereken birkaç belge sınıfı vardır:

Ürün / Yayın Belgeleri

Bu, 'bitmiş' ürününüzde ortaya çıkan herhangi bir şeydir. Bu sadece el kitaplarından daha fazlasıdır, bu README, Change Log, HOW-TO ve benzeridir. Teorik olarak, bunları yazmamaya başlayabilirsiniz, ancak insanların kullanmak istemedikleri bir ürün veya gereksiz yere pahalı bir destek yüküyle sonuçlanırsınız.

API Belgeleri

Bu, nispeten statik olması gereken bir şeyi açıklar . Çok sayıda tüketici API'nizi kodlayabildiğinden, nasıl kullanılacağını açıklayan bazı nesiller değere sahip olacak kadar yeterince kararlı olmalıdır. Hangi parametrelerin desteklendiğini, geri dönüş değerinin ne olabileceğini ve hangi hataların atılabileceğini tanımlamak, diğer kullanıcılara API'nizi doğru bir soyutlama düzeyinde anlama imkanı verir - arayüz ( uygulama değil ).

Kod Yorumları

Şu an, yorumlar hakkındaki sektör görüşü akı içinde görünüyor. Profesyonel olarak kodlamaya başladığımda, yorumlar yazı yazmaya geldiğinde olmazsa olmazlardandı . Şimdi, moda çok net bir kod yazmaktır, yorumlar gereksizdir. Tahmin ediyorum ki, bu, kısmen, birçok modern dilin çok daha yüksek bir seviyede yazılmasından ve Java, JavaScript, Ruby, vb. , C, FORTRAN, vs. Böylece, yorumlar çok daha büyük bir değere sahipti.

Yine de , bir kod bölümünün amacını açıklayan yorumlarda değere ya da belirli bir algoritmanın neden daha açık bir taneye göre seçildiğine dair bazı detayların bulunduğuna inanıyorum. Aslında düzeltilmesi gerekmiyor).

Ne yazık ki, programcıların belgelenmemesi kararlarında yer alan çok bencillik, rasyonalizasyon ve kendi kendine delüzyon var. Gerçek şu ki, kod gibi, belgeleme için birincil izleyici diğer insanlar. Bu nedenle, herhangi bir düzeyde dokümantasyon yazma (yazmama) kararları takım düzeyinde yapılması gereken karardır. Daha yüksek soyutlama seviyeleri için, geliştiriciler dışında birisinin yapması daha mantıklı olabilir. Yorum düzeyinde dokümantasyon gelince, yorumların amacı ve amacına yönelik bir anlaşmaya varılması, özellikle karışık yetenek ve deneyim ekiplerinde birlikte kararlaştırılmalıdır. Üst düzey geliştiricilerin, küçük geliştiricilerin yaklaşamayacağı kodlar yazması iyi değildir. Bazı iyi yerleştirilmiş ve iyi yazılmış belgeler bir ekibin çok daha etkili çalışmasına izin verebilir

İşte benim iki kuruş.

1. Agile Manifesto, "Kapsamlı belgeler üzerinden çalışma yazılımı" yazıyor ve herkes ulaşmak için okumaya devam etmiyor .

2. Ne yazık ki, https://en.wikipedia.org/wiki/Code_and_fix için sık rastlanır ve belgeler bu modelle çalışmaz (Senkronizasyondan çıkar).

3. Yazılım geliştirme endüstrisi iyi düzenlenmiş değildir. Belge yazmak için yasal bir zorunluluk yoktur.

4. Kendini belgeleyen kod mevcut eğilimdir.

Bunu söyledikten sonra, orada çok iyi belgeler olduğunu düşünüyorum.

Dokümantasyon zaman alıyor ve birçok geliştiricinin dokümantasyonda işe yaramazdan daha kötü dokümantasyon konusunda çok fazla çaba harcadığından şüpheleniyorum. Sadece belgelemekle menajerlerinden sorun çıkarmayacaklarını (programın QA bölümünü kesmeye devam eden aynı adam), ama onlar da dahil kimseye yardım etmeyeceği fikrine kapılıyorlar.

Herhangi bir yarı-terbiyeli belgelendirme, geleceğe yapılan bir yatırımdır. Geleceği umursamıyorsanız (bir sonraki maaşın ötesinde düşünmüyorsanız veya bunun sizin sorununuz olmayacağını düşündüğünüz için), o zaman dokümantasyon yapma düşüncesi son derece acı vericidir.

Diğer yanıtların çoğu, en az iki tür dokümantasyon olduğu noktasını vurgulamaktadır: biri diğer geliştiriciler için, diğeri de son kullanıcılar için farklı bir set. Ortamınıza bağlı olarak, sistem yöneticileri, montajcılar ve yardım masası personeli için ek belgelere de ihtiyacınız olabilir. Her hedef kitlenin farklı ihtiyaçları ve anlayış seviyeleri vardır.

(Stereo-) tipik geliştirici düşünün: O seçim tarafından bir kodlayıcıdır. Halkın gözünden bir kariyer seçti ve öncelikle kendisiyle iletişim klavyesini arkasında uzun saatler geçirdi. Dokümantasyon süreci bir iletişim şeklidir ve iyi dokümantasyon üretmek için gerekli olan beceri seti, iyi kod üretmek için gereken becerilere karşıdır.

İyi bir dokümantasyon yazarı birden fazla dilde iletişim kurabilir: kullanıcıların dili, yönetim dili, destek personeli dili, geliştiricilerin dili. Bir kodlayıcının neyle iletişim kurduğunu anlamak ve bunu diğer tüm grupların anlayabileceği bir forma dönüştürmek belgeleme yazıcısının işidir.

Kodlayıcıların iyi iletişimciler olmak için gerekli beceriyi geliştirmelerini beklediğinizde (yazılı veya başka şekilde), birincil beceri setini (kodlama!) Kazanmak için harcanan zaman miktarı azalır. Konfor bölgesinden uzaklaştıkça (diğer kodlayıcılarla kodlama ve iletişim kurma), görevi iyi yapmak için daha fazla zaman ve enerji gerekecektir. Profesyonel bir kodlayıcının, diğerlerinin pahasına, esasen temel yetkinliklerine odaklanmak istemesini makul bir şekilde bekleyebilirsiniz.

Bu nedenle dokümantasyon (satır içi kod açıklamaları hariç) kodlayıcılara değil, iletişimcilere bırakılmıştır.

Kodu okumak size nasıl çalıştığını gösterir . Nedenini açıklayamaz : Yorumlara ihtiyacınız var.

Kodu okumak size bir yöntemin adını ve parametre türlerini gösterir. Anlambilimi veya yazarın amacını açıklayamaz: Yorumlara ihtiyacınız var.

Yorumlar kodu okumak yerine geçmez, eklerler.

Belgeler kod olduğu gibi yürütülmez. Sonuç olarak, belgelerin yerinde ve eksiksiz olduğunu doğrulamak için genellikle etkili geri bildirim döngüleri yoktur. Bu, kod açıklamalarının çürümeye eğilimli olmasının aynı nedenidir.

Donald Knuth , dokümantasyon kodunu etkin bir şekilde yazarak, yazılımın kalitesini arttırmanın bir yolu olarak Literatür Programlamasını destekledi . Bu yaklaşımı oldukça etkili kullanan birkaç proje gördüm.

Şahsen kodunuzun genel API'sini olabildiğince okunaklı tutma eğilimine bağlı kalmaya ve diğer geliştiricilerin kullanımını belgelemek için birim sınamalarını kullanmaya çalışıyorum. Bunun, API'nizin keşfedilebilecek ve keşfedilebilecek bir formda olma fikrinin bir parçası olduğunu düşünüyorum. Bu yaklaşımın, HATEOAS'ın web servisleri ile neler başarmaya çalıştığının bir parçası olduğunu düşünüyorum .

Küçük bir nokta, ama iğrenç bir şekilde küçük belgeler yazan bazı geliştiriciler için önemli gibi görünen bir konu var: yazı yazamazlar. 10 parmak sistemine biraz yaklaşıyorsanız, kolay olduğu için daha fazla dokümantasyon yazabilirsiniz. Ama avlanma ve gagalama ile sıkışmışsanız kaybolursunuz. Eğer işe almaktan sorumlu olsaydım bu aslında kontrol edeceğim bir şeydi.

Belgeleri okumaktan hoşlanmayan kişiler, belgelere yazmaktan hoşlanmazlar. Bol miktarda programcı bir belgeyi iyice okumaktan kaçınmak için ellerinden geleni yapacaktır.

Yazmaya odaklanmayın, okumaya odaklanın. Programcılar belgeleri okurken ve onlardan bir şeyler özümlediğinde, değeri görecek ve bazılarını yazmaya daha meyilli olacaktır.

Mevcut işime başladığımda ve üzerinde daha önce çalışmış olan insanlardan donanım + yazılım projesini devraldığımda, sistemi açıklayan yüzlerce kelime ms belgesini aldım. Üretilmesi günler almış olmalı. İki kere baktım. Buradaki muazzam miktarda bilgiye rağmen, sistemle ilgili gerçek soruları nadiren cevapladı ve bu bile olsa bile, koda bakmak daha hızlı oldu.

Böyle yeterli deneyimlerden sonra düşünmeye başlarsın, neden rahatsız ediyorsun? Neden zamanınızı, insanların asla sormadığı soruları yanıtlamak için harcıyorsunuz? İnsanların dokümantasyonda hangi bilgileri arayacaklarını tahmin etmenin ne kadar zor olduğunu fark etmeye başladınız; kaçınılmaz olarak işe yaramaz, açık olmayan veya açık görünen ve en acil soruların cevaplarının bulunmadığı gerçeklerle doludur. Unutmayın, yararlı belgeler üretmenin insan davranışını öngörmede bir çaba olduğunu unutmayın. Bir kullanıcı arayüzü tasarımının, birçok test ve hata ayıklama yinelemesinden geçmeden önce başarılı olması pek mümkün olmadığından, sadece insanların sistemi nasıl yorumlayacağına dair beklentilere dayanan faydalı belgeler yazmanın mümkün olduğunu düşünmek saf değildir. Belgelerin ve dilinin bu yorumda oynayacağı rolü.

Belgelendirme yazma baskısının çoğunun, bunun hoş olmayan bir iş olduğu ve insanların birbirlerini hoş olmayan ev işleri yaparak suçlamasını sevdikleri gerçeğinden kaynaklandığını düşünme eğilimindeyim.

ANCAK

Belgelerin her şekilde, umutsuz olduğunu düşünmüyorum. Öncelikle, insanlar dokümantasyona bir iş bitmeden yerine getirilmesi gereken bu ekstra yük, acele edilmesi gereken son temizlik işi ve kontrol edilmesi gereken bir kutu olarak bakıldığında umutsuz olduğunu düşünüyorum. Belgeleme, gününüzü yine de yapmanız gereken yönleri üzerinde çalışmanız gereken bir şeydir. Bence e-posta, dokümantasyon yapmak için özellikle iyi bir yol. Yeni bir özellik eklediğinizde, birkaç kişiye ne olduğunu söyleyerek hızlı bir e-posta yazın. Yeni bir şematik çizerken, bir PDF oluşturun ve ilgilenen herkese gönderin. E-postanın avantajları:

1. İnsanlar genellikle e-postalarını kontrol eder, oysa kimse "doc" adlı bir klasöre girmez.

2. E-posta, özelliği ve ilgili özellikleri ve o sırada olan diğer şeyleri tartışan diğer e-postalarla çevrili bağlamda mevcuttur.

3. E-posta kısa ve odaklanmış ve konu satırı var.

4. E-posta, hemen soru sormak isteyen kişilere izin verir,

5. E-posta oldukça aranabilir, çünkü insanlar onu her şey için kullanıyor ve posta istemcileri yıllar içinde biraz daha gelişti.

6. Bir e-postadaysa, en az bir kişi onu nerede bulacağını bilir.

Teoride, koddaki yorumların aynı zamanda “her zaman yaptığınız gününüzün bir yönü” olması gerektiği anlaşılmalıdır, ancak dürüst olmak gerekirse, koddaki yorumları asla okumam. Neden olduğundan emin değilim, ama çok yardımcı olmadıklarından, belki de e-postanın çözdüğü bağlam eksikliği nedeniyle.