'Dokümantasyon' tam olarak neler içerir?

Bir yazılım ürünü için 'dokümantasyon' dediğimizde neleri içerir ve neleri içermemelidir?

Örneğin, yakın tarihli bir soru yorumların belge olarak kabul edilip edilmediğini sordu

Ancak bunun geçerli bir soru olduğu başka alanlar da var, bazıları diğerlerinden daha açık:

• Kılavuzlar (açıkçası)
• Sürüm notları?
• Öğreticiler
• Yorumlar
• Herhangi diğerleri?

Çizgi nerede çizilir. Örneğin, 'öğretici' dokümantasyonsa, 'öğretici' dokümantasyon mu yoksa başka bir şey mi?

Genellikle, yazılımdaki bir şey uygulanana, test edilip belgelenene kadar 'yapılmaz'. Bu nedenle, bu soruyu, 'yapılan' bir şeyi düşünmek için belgenin bir parçası olarak neleri dikkate almalıyız?

_{Soru, konferansımızdaki son müşteri geri bildirimlerinden ilham alarak, doktorumuzun daha önce olması gerektiği kadar iyi düşünmediğimiz daha fazla 'örneğe' ihtiyacı olduğunu gösterdi.}

_{Kitle: Veritabanlarımızı, programlama dillerini ve ilgili araçları (yazılım istemcileri tarafından bahsedilen DB'ye) kullanan yazılım geliştiricileri}

Dokümantasyonun amacı yazılım ürününü tanımlamak ve açıklamaktır, böylece dokümantasyonu bu açıklamaya veya açıklamaya katkıda bulunan eserler kümesi olarak tanımlayabilirsiniz. Muhtemelen ilgili eylemleri dokümantasyonun bir parçası olarak görmezsiniz : örn. Bir haftalık eğitim kursu dokümantasyon değil, kurs materyalleri; beş dakikalık bir beyaz tahta sohbeti dokümantasyon değil, beyaz tahtanın bir görüntüsüdür.

Hedefi (yazılımı açıklayan) akılda tutarak, müşteri açıklamadan memnun olduğunda dokümantasyon biter : tıpkı müşteri yazılımdan memnun olduğunda yazılım bitmiş gibi. Dokümantasyon müşterisinin her zaman yazılım için ödeme yapan müşteriyle aynı olmadığını unutmayın: destek personeli, test uzmanları, satış görevlileri ve diğerlerinin yazılımın ne yaptığını ve nasıl çalıştığını anlaması gerekir.

Bu, belgelere nelerin dahil edilmesi gerektiğine ilişkin sınırınızın nerede olduğunu anlamanıza yardımcı olur. "Okuyucu" yu kullanışlı bir stenografi olarak kullanmakla birlikte, videoların veya sesin dahil edilebileceğini kabul ediyoruz: okuyucunun yazılım hakkında ihtiyaç duydukları bilgileri edinmesine yardımcı olan herhangi bir şey kullanabilecekleri belgelerdir, diğer her şey değildir. Müşterinizin tüm kullanım durumlarının ayrıntılı gözden geçirmelerine ihtiyacı varsa, bunun belgelerin bir parçası olması gerekir. Geliştiricileriniz muhtemelen kaynak koduna, sürüm kontrol deponuzla ilgili bilgilere ve derleme talimatlarına ihtiyaç duyarlar: bu onlar için belgelerdir, ancak yukarıda açıklandığı gibi müşterinin belgelerinin bir parçası olmaz.

Sanırım konferansta yaptığınız görüşmeden yanlış tarafı çıkardınız. Modern yazılım geliştirme metodolojileri, geliştirme ekibinin müşterileriyle (veya müşteri vekili olarak hareket eden bir ürün sahibiyle) yakın bir şekilde çalışması gerektiğini savunur. Teslim edilen tüm işler için, "tamamlandı" tanımı, ekip ve müşterisi arasında müzakere edilen ve yazılım geliştirilirken yinelenen bir temelde yapılan bir şeydir.

Karşılaştığınız sorun, müşterinin ihtiyaç duyduğu varsayım ile sizden teslim etmenizi bekledikleri şey arasında bir kopukluğunuz olmasıydı.

Bildiğim kadarıyla, dokümantasyon nedir ... iyi, listelediğiniz hemen hemen her şey ve belki de yapmadığınız birkaç şey daha. Ancak kimse size projenizin ne kadar dokümantasyona ihtiyacı olduğunu söyleyemez. Her proje farklıdır ve projeniz için gerekli olan belge düzeyini ve türünü belirlemek ekibinize, ürün sahibinize ve müşterilerinize bağlıdır.

Oyuna girebilecek bazı faktörler:

• Yazılım v1.0 geliştiriyor musunuz ve diğer projelere geçiyor musunuz, yoksa bu devam eden uzun vadeli bir proje mi? Yorumlar / tasarım belgeleri ikinci durumda çok daha önemli hale gelir. Öte yandan müşteriniz bir anne-pop çörek dükkanı ve onlar için asla göremeyeceğiniz bir web sitesi yazıyorsanız ... iyi sanırım kod belgeleri güzel ama önemli değil.
• Bir hastanede kalp atış hızı monitörünü kontrol eden bir mobil oyun veya yazılım geliştiriyor musunuz? Hangisinin çok daha fazla dokümantasyona sahip "tamamlanmış" tanımına sahip olacağını tahmin edin?
• Müşterileriniz tipik son kullanıcılar mı yoksa başka geliştiriciler mi? Gösterdiğiniz bir API / SDK'nız var mı?
• Müşterilerinizin uzmanlık seviyesi nedir? Bu, bir tür etkileşimli öğretici uygulamaya karşı video eğitimi ve yazılı materyal seçimini etkiler
• Müşterileriniz sürümden sürüme nelerin değiştiğini önemsiyorlar mı? Bazıları yapar. Çoğu bilmiyor. Birkaçı için bakım yasa (veya buna yakın).

Belgeler, değiştirilmeden okunması amaçlanan şeylerdir.

Bence amaca dayalı tanımla yanlış gidemezsiniz ... ama sadece amacı doğru bir şekilde tanımlarsanız.

• ^{Dokümantasyon amacını doğru bir şekilde tanımlamak oldukça basit değildir. Doğal olarak akla gelen basit (isterseniz naif) ayrım, belgelemenin okuma için tasarlanan her şey olduğu, karşılaştırma için ise kod bilgisayar yürütmesi için tasarlanmış bir şey olduğu yönündedir . Yüzeyde kulağa hoş geliyor değil mi? ama daha derine inince çok çirkinleşiyor.
   
  Şey, iyi kod, yürütme doğruluğu ile birlikte okunabilirlik endişelerini dikkate alır - bu, "okunabilirlik" ayrımını belgelerin tanımlanmasında oldukça işe yaramaz hale getirir.
   
  Çok numuneler bunun nesi göstermek bahsettiniz. Müşteriler genellikle bunların açıkça yazılmasını vedoğru yürütmek. Okunabilirlik veya doğruluktan ödün vermek, müşteri şikayetlerinin bir şelalesine yol açabilir. Saf ayrım örneklerin kod veya belge olup olmadığını anlamaya yardımcı olmaz. Açık kaynakla
   
  çalışmayı hayal ederseniz saf bir ayrım kullanmak daha da dağınık hale gelecektir . İndiriyor, oluşturuyor ve çalıştırıyorsunuz - okumuyorsunuz, bu sadece kod değil mi? Bekle, bir şekilde bir şeyler ters gitti ve orada neler olduğunu okumak için koda ulaşıyorsun ... hey okudum değil yürütmek - bu dokümantasyon şimdi mi? Ve son olarak, kaynakta hata buluyor ve düzeltiyorsunuz - şimdi bu gerçekten kod, bu düzeltmeyi yapmak için ne kadar dikkatli okursanız olun, normalde dokümantasyon olarak adlandırılan bir şey değil.}

Sağlayacağınız 'örnekler' için, değiştir ve değiştir okuması ayrımı oldukça önemli olabilir.

Belli referans ortamında bazı örnekler değişmeden çalıştırıldığında başarısız olursa, dokümantasyonunuzdaki hata - hata ve kabul etmeniz ve düzeltmeniz gereken sorun.

Şimdi, değiştirilmiş örnek veya ortamla ilgili bir sorun varsa, artık sizin hatanız değil - dokümanlar değişiklik için tasarlanmadığı için dokümantasyonda hata yok. Böyle bir durumda kullanıcılara yardımcı olmanız ne olursa olsun, bir hata düzeltme değil destek kategorisine girer.

"Nasıl yapılır ..." sorusunu cevaplayan her şey belgelerdir.

Geliştiriciler için bu, şartname spesifikasyonları ("ne yazacağımı nasıl bilirim"), tasarım belgeleri ("şartlarımı nasıl ele alırım"), izlenebilirlik matrisleri ("tasarladığımın tüm şartlarımı karşıladığını nasıl bilebilirim "), test planları ( "Ben kod çalıştığını biliyorum nasıl"), birim testleri ( "Ben safisfied gereklilik X ettik biliyor musunuz nasıl"), nasıl ben yazdım neden emin sonraki yoksul schlub anlayan yapabilirim satır içi yorumları ( " bu yolu "), dağıtım talimatları (" bu ürünü kurulum için nasıl paketlerim ") vb.

Kullanıcılar için bu, kullanıcı kılavuzları ("yazılımı nasıl kullanırım"), öğreticiler ("bu özel özelliği nasıl kullanırım"), sürüm notları ("hangi hataların giderildiğini nasıl bilebilirim / yeni hata özellikleri olduğunu gösterir) eklendi "), vb.