Merhaba Habr! Adım Lesha, Alfa-Bank'ın ürün ekiplerinden birinde sistem analistiyim. Şimdi tüzel kişiler ve bireysel girişimciler için yeni bir çevrimiçi banka geliştiriyorum.
Ve analist olduğunuzda, özellikle de böyle bir kanalda, dokümantasyon olmadan ve onunla yakın çalışmadan bir yere varamazsınız. Ve dokümantasyon her zaman birçok soruyu gündeme getiren bir şeydir. Web uygulaması neden açıklanmıyor? Spesifikasyon neden hizmetin nasıl çalışması gerektiğini gösteriyor ancak hiç bu şekilde çalışmıyor? Neden sadece biri bunu yazan iki kişi spesifikasyonu anlayabiliyor?
Ancak belgeler bariz nedenlerden dolayı göz ardı edilemez. Hayatımızı kolaylaştırmak için dokümantasyonun kalitesini değerlendirmeye karar verdik. Bunu tam olarak nasıl yaptığımız ve hangi sonuçlara vardığımız kesimin altında.
Dokümantasyon kalitesi
Metinde “Yeni İnternet Bankası” nı onlarca kez tekrarlamamak için NIB yazacağım. Artık girişimciler ve tüzel kişiler için NIB'nin geliştirilmesi üzerinde çalışan bir düzineden fazla ekibimiz var. Üstelik her biri ya yeni bir hizmet ya da web uygulaması için kendi dokümantasyonunu sıfırdan oluşturuyor ya da mevcutta değişiklik yapıyor. Bu yaklaşımla dokümantasyon prensipte yüksek kalitede olabilir mi?
Dokümantasyonun kalitesini belirlemek için üç ana özellik belirledik.
- Tamamlanmış olmalı. Bu oldukça kaptana benziyor, ancak bunu not etmek önemlidir. Uygulanan çözümün tüm unsurlarını ayrıntılı olarak açıklamalıdır.
- İlgili olmalı. Yani, çözümün kendisinin mevcut uygulamasına karşılık gelir.
- Anlaşılabilir olmalıdır. Böylece kullanan kişi çözümün nasıl uygulandığını tam olarak anlar.
Özetlemek gerekirse - eksiksiz, güncel ve anlaşılır belgeler.
Опрос
Belgelerin kalitesini değerlendirmek için doğrudan onunla çalışan kişilerle, yani NIB analistleriyle röportaj yapmaya karar verdik. Katılımcılardan 10 ifadeyi “1'den 5'e kadar (tamamen katılmıyorum - tamamen katılıyorum)” şemasına göre değerlendirmeleri istendi.
İfadeler, niteliksel dokümantasyonun özelliklerini ve anket derleyicilerinin NIB dokümanlarına ilişkin görüşlerini yansıtıyordu.
- NIB uygulamalarına ilişkin belgeler günceldir ve bunların uygulanmasıyla tamamen tutarlıdır.
- NIB uygulamalarının uygulanması tamamen belgelenmiştir.
- NIB uygulamalarına yönelik belgeler yalnızca işlevsel destek için gereklidir.
- NIB başvurularına ilişkin belgeler, işlevsel destek için başvuru sırasında günceldir.
- NIB uygulama geliştiricileri neyi uygulamaya ihtiyaçları olduğunu anlamak için belgeleri kullanır.
- NIB uygulamalarının nasıl uygulandıklarını anlamak için yeterli belge bulunmaktadır.
- NIB projelerine ilişkin belgeleri (ekibim tarafından) sonuçlandırılırsa derhal güncellerim.
- NIB uygulama geliştiricileri belgeleri inceliyor.
- NIB projeleri için dokümantasyonun nasıl hazırlanacağına dair net bir anlayışa sahibim.
- NIB projeleri için belgelerin ne zaman yazılacağını/güncelleneceğini anlıyorum.
Basitçe "1'den 5'e" yanıtını vermenin gerekli ayrıntıları ortaya çıkarmayabileceği açıktır, dolayısıyla kişi her öğeye yorum bırakabilir.
Tüm bunları kurumsal Slack aracılığıyla yaptık; sistem analistlerine ankete katılmaları için bir davet gönderdik. 15 analist vardı (9'u Moskova'dan ve 6'sı St. Petersburg'dan). Anket tamamlandıktan sonra 10 ifadenin her biri için ortalama bir puan oluşturduk ve bunu standartlaştırdık.
Anlaşıldı ne oldu.
Anket, analistlerin NIB uygulamalarının uygulanmasının tamamen belgelendiğine inanma eğiliminde olmalarına rağmen, kesin bir fikir birliğine varmadıklarını gösterdi (0.2). Spesifik bir örnek olarak, mevcut çözümlere ait bazı veritabanlarının ve kuyrukların dokümantasyon kapsamına girmediğine dikkat çektiler. Geliştirici analistlere her şeyin belgelenmediğini söyleyebilir. Ancak geliştiricilerin belgeleri gözden geçirdiği tezi de kesin bir destek alamadı (0.33). Yani uygulanan çözümlerin eksik tanımlanması riski devam etmektedir.
İlgililik daha kolaydır - yine net bir anlaşma olmamasına rağmen (0,13), analistler hala dokümantasyonun ilgili olduğunu düşünme eğilimindedir. Yorumlar, alaka düzeyiyle ilgili sorunların ortada olmaktan çok ön planda olduğunu anlamamızı sağladı. Ancak bize destek konusunda hiçbir şey yazmadılar.
Analistlerin dokümantasyonun ne zaman yazılması ve güncellenmesi gerektiğini anlayıp anlamadıklarına gelince, anlaşma tasarımı (1,33) dahil olmak üzere çok daha tekdüzeydi (1.07). Burada bir rahatsızlık olarak kaydedilen şey, dokümantasyonun korunmasına ilişkin tek tip kuralların bulunmamasıydı. Dolayısıyla “Kim ormana gider, kim yakacak odun alır” modunu açmamak için mevcut belge örneklerine göre çalışmak zorundalar. Bu nedenle, belge yönetimi için bir standart oluşturmak ve bunların bölümleri için şablonlar geliştirmek faydalı bir dilektir.
NIB başvurularına ilişkin belgeler, işlevsel destek için başvuru sırasında günceldir (0.73). Bu anlaşılabilir bir durumdur çünkü bir projeyi işlevsel destek için gönderme kriterlerinden biri güncel belgelerdir. Bazen sorular kalsa da uygulamayı anlamak da yeterlidir (0.67).
Ancak katılımcıların (kesinlikle oybirliğiyle) NIB başvurularına yönelik dokümantasyonun prensip olarak yalnızca işlevsel destek için gerekli olduğu konusunda hemfikir olmadığı (-1.53) oldu. Analistlerden en çok belgelerin tüketicileri olarak bahsediliyordu. Ekibin geri kalanı (geliştiriciler) - çok daha az sıklıkla. Üstelik analistler, geliştiricilerin, oybirliğiyle olmasa da (-0.06) neyi uygulamaya ihtiyaçları olduğunu anlamak için belgeleri kullanmadıklarına inanıyor. Bu arada, kod geliştirme ve dokümantasyon yazımının paralel ilerlediği koşullarda da bu beklenen bir durumdur.
Sonuç olarak nedir ve neden bu sayılara ihtiyacımız var?
Belgelerin kalitesini artırmak için aşağıdakileri yapmaya karar verdik:
- Geliştiriciden yazılı belgeleri incelemesini isteyin.
- Mümkünse belgeleri zamanında, önce ön kısmı güncelleyin.
- Herkesin hangi sistem öğelerinin ve tam olarak nasıl tanımlanması gerektiğini hızlı bir şekilde anlayabilmesi için NIB projelerini belgelemek için bir standart oluşturun ve benimseyin. Peki, uygun şablonlar geliştirin.
Bütün bunlar belgelerin kalitesinin yeni bir seviyeye yükseltilmesine yardımcı olacaktır.
En azından böyle umuyorum.
Kaynak: habr.com