Witaj, Habro! Nazywam się Lesha, jestem analitykiem systemowym w jednym z zespołów produktowych Alfa-Banku. Obecnie rozwijam nowy bank internetowy dla osób prawnych i przedsiębiorców indywidualnych.
A kiedy jesteś analitykiem, szczególnie w takim kanale, bez dokumentacji i ścisłej pracy z nią nie możesz się nigdzie obejść. A dokumentacja zawsze rodzi wiele pytań. Dlaczego aplikacja internetowa nie została opisana? Dlaczego specyfikacja wskazuje, jak usługa ma działać, a wcale tak nie działa? Dlaczego tylko dwie osoby, z których jedna to napisała, są w stanie zrozumieć specyfikację?
Dokumentacji nie można jednak z oczywistych powodów zignorować. Aby ułatwić nam życie, postanowiliśmy ocenić jakość dokumentacji. Jak dokładnie tego zrobiliśmy i do jakich wniosków doszliśmy, poniżej.
Jakość dokumentacji
Aby nie powtarzać w tekście słowa „Nowy Bank Internetowy” kilkadziesiąt razy, napiszę NIB. Obecnie nad rozwojem NIB dla przedsiębiorców i osób prawnych pracuje kilkanaście zespołów. Co więcej, każdy z nich albo tworzy od podstaw własną dokumentację dla nowej usługi lub aplikacji internetowej, albo dokonuje zmian w już istniejącej. Czy przy takim podejściu dokumentacja może być w zasadzie wysokiej jakości?
Aby określić jakość dokumentacji, zidentyfikowaliśmy trzy główne cechy.
- Musi być kompletne. Brzmi to raczej jak kapitan, ale warto o tym pamiętać. Powinien szczegółowo opisywać wszystkie elementy wdrażanego rozwiązania.
- Musi być aktualne. Oznacza to, że odpowiadają bieżącej realizacji samego rozwiązania.
- To powinno być zrozumiałe. Aby osoba korzystająca z niego dokładnie rozumiała, w jaki sposób rozwiązanie jest realizowane.
Podsumowując - dokumentacja kompletna, aktualna i zrozumiała.
Wywiad
Aby ocenić jakość dokumentacji, postanowiliśmy przeprowadzić wywiady z osobami, które bezpośrednio z nią pracują: analitykami NIB. Respondenci zostali poproszeni o ocenę 10 stwierdzeń według schematu „W skali od 1 do 5 (całkowicie się nie zgadzam – całkowicie się zgadzam).”
Stwierdzenia odzwierciedlały cechy dokumentacji jakościowej oraz opinię autorów badania na temat dokumentów NIB.
- Dokumentacja wniosków NIB jest aktualna i w pełni zgodna z ich realizacją.
- Wdrożenie aplikacji NIB jest w pełni udokumentowane.
- Dokumentacja aplikacji NIB jest potrzebna jedynie do wsparcia funkcjonalnego.
- Dokumentacja wniosków NIB jest aktualna w momencie ich złożenia do wsparcia funkcjonalnego.
- Twórcy aplikacji NIB korzystają z dokumentacji, aby zrozumieć, co muszą wdrożyć.
- Istnieje wystarczająca dokumentacja aplikacji NIB, aby zrozumieć, w jaki sposób są one wdrażane.
- Natychmiast aktualizuję dokumentację projektów NIB, jeśli zostaną one sfinalizowane (przez mój zespół).
- Twórcy aplikacji NIB przeglądają dokumentację.
- Doskonale rozumiem, jak przygotować dokumentację dla projektów NIB.
- Rozumiem, kiedy pisać/aktualizować dokumentację dla projektów NIB.
Oczywiste jest, że sama odpowiedź „Od 1 do 5” może nie ujawnić niezbędnych szczegółów, więc osoba może zostawić komentarz do każdej pozycji.
Wszystko to zrobiliśmy poprzez korporacyjny Slack – po prostu wysłaliśmy zaproszenie do analityków systemowych do wzięcia udziału w ankiecie. Analityków było 15 (9 z Moskwy i 6 z Petersburga). Po zakończeniu ankiety dla każdego z 10 stwierdzeń wygenerowaliśmy średni wynik, który następnie ujednoliciliśmy.
Oto co się stało.
Badanie wykazało, że choć analitycy skłonni są wierzyć, że wdrożenie aplikacji NIB jest w pełni udokumentowane, to nie dają jednoznacznej zgody (0.2). Jako konkretny przykład wskazali, że szereg baz danych i kolejek z istniejących rozwiązań nie zostało objętych dokumentacją. Deweloper jest w stanie powiedzieć analitykowi, że nie wszystko jest udokumentowane. Ale teza, że programiści przeglądają dokumentację, również nie uzyskała jednoznacznego wsparcia (0.33). Oznacza to, że ryzyko niepełnego opisu wdrożonych rozwiązań pozostaje.
Trafność jest łatwiejsza – chociaż ponownie nie ma jednoznacznej zgodności (0,13), analitycy nadal są skłonni uważać dokumentację za istotną. Komentarze pozwoliły nam zrozumieć, że istotne problemy częściej występują z przodu niż pośrodku. Jednak nic nam nie napisali w sprawie wsparcia.
Jeśli chodzi o to, czy sami analitycy rozumieją, kiedy konieczne jest pisanie i aktualizacja dokumentacji, umowa była znacznie bardziej jednolita (1,33), także jej projekt (1.07). Jako niedogodność wskazano tutaj brak jednolitych zasad prowadzenia dokumentacji. Dlatego, aby nie włączać trybu „Kto idzie do lasu, kto dostaje drewno na opał”, muszą pracować w oparciu o przykłady istniejącej dokumentacji. Dlatego pożytecznym życzeniem jest stworzenie standardu zarządzania dokumentami i opracowanie szablonów dla ich części.
Dokumentacja wniosków NIB jest aktualna w momencie składania wniosku o wsparcie funkcjonalne (0.73). Jest to zrozumiałe, gdyż jednym z kryteriów zgłoszenia projektu do wsparcia funkcjonalnego jest aktualna dokumentacja. Wystarczy również zrozumieć implementację (0.67), chociaż czasami pozostają pytania.
Natomiast to, z czym respondenci nie zgodzili się (całkiem jednomyślnie), to fakt, że dokumentacja do aplikacji NIB w zasadzie potrzebna jest jedynie do wsparcia funkcjonalnego (-1.53). Jako konsumenci dokumentacji najczęściej wymieniani byli analitycy. Reszta zespołu (programiści) - znacznie rzadziej. Co więcej, analitycy uważają, że programiści nie korzystają z dokumentacji, aby zrozumieć, co muszą wdrożyć, chociaż nie są to jednomyślni (-0.06). Nawiasem mówiąc, jest to również oczekiwane w warunkach, w których tworzenie kodu i pisanie dokumentacji przebiegają równolegle.
Jaki jest ostateczny wynik i dlaczego potrzebujemy tych liczb?
Aby poprawić jakość dokumentów, postanowiliśmy wykonać następujące czynności:
- Poproś programistę o przejrzenie pisemnych dokumentów.
- Jeśli to możliwe, aktualizuj dokumentację w odpowiednim czasie, najpierw od przodu.
- Stwórz i przyjmij standard dokumentowania projektów NIB, aby każdy mógł szybko zrozumieć, które elementy systemu i jak dokładnie należy opisać. Cóż, opracuj odpowiednie szablony.
Wszystko to powinno pomóc podnieść jakość dokumentów na nowy poziom.
Przynajmniej mam taką nadzieję.
Źródło: www.habr.com