Budowa systemu informatycznego to długi i skomplikowany proces. Równie trudna jest ocena jakości zbudowanego już systemu. Użytkownikom może się on podobać lub nie.
System subiektywnie może działać szybko lub wolno, jego architektura może być skalowalna i nowoczesna lub zupełnie przeciwnie, a sam kod przejrzysty i wydajny lub przypominający włoskie spaghetti. Pośród tych wielu wskaźników pomijamy często jakość (lub wręcz istnienie) dokumentacji rozwiązania.
Dwie strony medalu
Pracując od wielu lat w IT, zauważyłem dwa ciekawe trendy w temacie dokumentacji. Pierwszy z nich to fakt, że wielu początkujących programistów, wewnętrznych działów IT i firm świadczących „tanie” usługi informatyczne robi wszystko, aby nie pozostawić po sobie żadnej dokumentacji. Słowo „żadnej” obejmuje też sytuacje, w których po rocznym projekcie na 1000 roboczodni przygotowanie dokumentacji i szkolenia zamykają się w 10. Dobrze wiemy, że te 10 dni to tylko listek figowy przykrywający to, czego nie chcemy wprost pokazywać.
Tak bardzo przyzwyczailiśmy się do tej niskiej jakości dokumentacji, że często spotykam się w trakcie negocjacji handlowych z pytaniem: A czemu ta dokumentacja jest tak droga? Przyznam się, że to pytanie przywodzi mi na myśl postawę pilotów samobójców, którzy w trasę zabierają tylko połowę paliwa, bo i tak nie zamierzają wracać.
Jeszcze bardziej podkreśla tę sytuację fakt, że po przekazaniu takiej dobrze wykonanej dokumentacji padają słowa: To najlepiej wykonana dokumentacja, jaką w życiu widziałem. I byłoby to pewnie bardzo budujące, gdybym nie wiedział, jak nisko zawieszona jest poprzeczka.
Co dokumentować?
Nasuwa się pytanie – co należy dokumentować. Najprostsza odpowiedź brzmi: wszystko. Zaczynając od dokumentów powstających w trakcie projektu, takich jak analiza biznesowa, architektura systemu czy plan testów. Oprócz tego potrzebujemy jednakowych dla całej organizacji standardów kodu, bezpieczeństwa, procesów CI/CD, układu repozytorium czy sposobu dokumentacji samego kodu. Z kolei po zakończeniu projektu przydadzą się dokumenty opisujące sposób działania systemu, podręczniki użytkownika i administratora.
Oczywiście specyficzne obszary IT będą wymagały dodatkowych form dokumentacji. Na przykładzie najbliższego mi obszaru danych będziemy potrzebowali dodatkowo: modelu danych, dokumentu opisującego mapowanie, transformacje, znaczenie biznesowe i techniczne danych, standardy orkiestracji oraz dokumentację raportów.
Dlaczego dokumentować?
Z doświadczenia powiem, że nie ma nic lepszego pierwszego dnia pracy programisty w nowej firmie niż informacja, że będzie się mierzył z procedurą SQL mającą 4000 linii kodu i ani jednej linii dokumentacji. Podpowiedzi typu: „domyślisz się”, „zapytaj biznes” lub „to nie nasza wina, że autor tego dzieła się zwolnił” tylko przyśpieszają decyzję o potrzebie poszukania kolejnego miejsca zatrudnienia.
Bez dobrej dokumentacji utrata pracownika autora kodu to dramat. Bez dobrej dokumentacji próba rozszerzenia zespołu o nowych specjalistów – dramat. Bez dobrej dokumentacji próba przypomnienia sobie, co robi ten kod, podjęta przez jego autora po roku niezaglądania do niego – kolejny dramat. Bez dobrej dokumentacji system IT zamienia się w „legacy” już w momencie jego uruchomienia.
Łukasz Nienartowicz
Britenet
