Dobra dokumentacja projektu IT ma sprawić, że system da się zrozumieć i rozwijać bez ciągłego odwoływania się do jego autorów.

Dlaczego sam działający system nie wystarczy?

Kod pokazuje, jak system działa w danym momencie. Znacznie gorzej radzi sobie z odpowiedzią na pytanie, dlaczego powstał właśnie w taki sposób.

Z samego kodu trudno wywnioskować, że nietypowa integracja wynika, na przykład, z ograniczeń operatora płatności. Nie widać też, że określony proces jest krytyczny dla firmy albo że zespół świadomie zaakceptował mniej eleganckie rozwiązanie, żeby zdążyć przed ważnym terminem.

Ma to szczególne znaczenie przy kolejnych zmianach w systemie.

Po czasie zespół może uznać jakiś fragment systemu za niepotrzebnie skomplikowany i spróbować go uprościć. Na przykład usunąć dodatkowy krok w procesie zamówienia, który z technicznego punktu widzenia wydaje się zbędny. W rzeczywistości może on wynikać z wymagań księgowości albo integracji z systemem magazynowym. Bez tego kontekstu łatwo takimi działaniami doprowadzić do błędów.

Dokumentacja przechowuje właśnie ten kontekst. Nie powinna opisywać kodu linijka po linijce. Powinna pomagać zrozumieć, co system robi, dlaczego robi to w określony sposób i jakie ograniczenia trzeba brać pod uwagę przy dalszym rozwoju.

Co powinna zawierać dokumentacja projektu IT?

Nie potrzebujesz jednego rozbudowanego dokumentu, żeby mieć „wszystko w jednym miejscu”. Znacznie ważniejsze jest, żeby potrzebne informacje dało się szybko znaleźć i wykorzystać.

W praktyce warto zadbać o kilka obszarów:

• Mapa projektu. Gdzie znajdują się najważniejsze materiały, kod, środowiska i narzędzia? Od czego powinna zacząć nowa osoba?
• Cel produktu i kontekst biznesowy. Dla kogo powstał system, jaki problem rozwiązuje i które procesy mają największe znaczenie dla firmy?
• Procesy biznesowe i reguły. Jak przebiegają najważniejsze operacje? Jakie są role użytkowników, wyjątki i zasady, których system musi przestrzegać?
• Specyfikacje kluczowych funkcji. Po co dana funkcjonalność istnieje, jakiego efektu oczekujemy i kiedy można uznać, że działa prawidłowo?
• Architektura systemu i zależności. Jakie są główne moduły, integracje i przepływy danych? W tym miejscu prosty diagram często daje więcej niż kilka stron tekstu.
• Decyzje wraz z uzasadnieniem. Nie tylko „wybraliśmy X”, ale także „wybraliśmy X, ponieważ...”.
• Znane problemy i ograniczenia. Jeżeli jakiś element systemu jest ryzykowny, przestarzały albo wymaga późniejszej przebudowy, kolejna osoba powinna o tym wiedzieć.

Jeśli produkt rozwija firma zewnętrzna, warto też ustalić jakiej dokumentacji wymagać od dostawcy oprogramowania. Samo posiadanie dostępu do kodu nie oznacza jeszcze, że przekazywana jest wiedza potrzebna do jego utrzymania.

Dobra dokumentacja techniczna systemu musi nadążać za zmianami

Dokumentacja jest użyteczna tylko wtedy, gdy można jej ufać. Materiał opisujący stan systemu sprzed dwóch lat bywa bardziej problematyczny niż jego całkowity brak.

Stare informacje, które nadal wyglądają aktualnie, bywają wręcz niebezpieczne dla projektu.

Załóżmy, że ktoś trafi na opis procesu, założy, że nadal obowiązuje, i podejmie na tej podstawie jakąś decyzję. Konsekwencje takiej decyzji ciężko przewidzieć, ale rzadko bywają zerowe. Jej rezultatem może po prostu być wzrost długu technicznego. Albo krytyczny błąd na produkcji.

Dlatego nie warto mierzyć jakości dokumantacji liczbą stron.

Krótki opis aktualizowany razem z projektem może być znacznie cenniejszy niż duży PDF przygotowany raz, na starcie projektu. Jeśli dochodzi nowa integracja, trzeba ją uwzględnić na diagramie. Jeśli zmienia się proces biznesowy, trzeba poprawić jego opis. Jeśli wcześniejsza decyzja przestała obowiązywać, trzeba to jednoznacznie zaznaczyć.

Jak sprawdzić, czy dokumentacja faktycznie działa?

Najlepszym testem nie jest sprawdzenie czy ktoś spoza dotychczasowego zespołu potrafi z niej skorzystać.

Możesz użyć kilku prostych pytań:

• Czy nowa osoba wie, od którego materiału zacząć?
• Czy potrafi zrozumieć podstawowy proces biznesowy bez rozmowy z jego autorem?
• Czy znajduje uzasadnienie ważnej decyzji, a nie tylko opis jej efektu?
• Czy dokumentacja pokazuje aktualny stan systemu?
• Czy wiadomo, które części rozwiązania wymagają szczególnej ostrożności?

Jeśli większość odpowiedzi wymaga dopowiedzenia „zapytaj osobę, która to robiła”, wiedza nadal nie została skutecznie przekazana.

To szczególnie dobrze widać przy onboardingu. Nowy pracownik zawsze będzie potrzebował czasu na poznanie produktu. Nie powinien jednak spędzać pierwszych tygodni na ustalaniu, gdzie (lub, co gorsza, u kogo) w ogóle szukać podstawowych informacji.

Dokumentacja ułatwia zmianę dostawcy oprogramowania

Braki w dokumentacji najwięcej kosztują wtedy, gdy zmieniają się ludzie odpowiedzialni za system.

Firma może mieć pełne prawa do oprogramowania, dostęp do kodu i komplet podpisanych umów. Ale nowy zespół nadal może nie wiedzieć, jak bezpiecznie rozwijać produkt.

Wtedy trzeba zacząć od odtwarzania kontekstu. Czytać stare zadania, historię zmian i fragmenty komunikacji. Próbować ustalić, które zachowania systemu są błędami, a które wynikają ze świadomych decyzji. W praktyce płaci się wtedy za ponowne zdobywanie wiedzy, którą ktoś wcześniej już posiadał.

Dobra dokumentacja ogranicza ten koszt. Nie sprawi, że zmiana wykonawcy będzie całkowicie bezproblemowa, ale zmniejszy zależność od pojedynczych osób i poprzedniego dostawcy.

Co zrobić, gdy dokumentacji praktycznie nie ma?

Przy zmianie wykonawcy nie warto zaczynać od próby opisania całego systemu od zera. Najpierw trzeba odzyskać kontrolę nad tym, co jest potrzebne do jego działania.

Priorytetem są dostęp do kodu, infrastruktury, baz danych, środowisk i usług zewnętrznych. Równolegle trzeba ustalić, które procesy są krytyczne dla firmy i kto nadal posiada wiedzę o ich działaniu.

Dopiero na tej podstawie można stopniowo odbudowywać dokumentację.

Dlatego przejęcie projektu technologicznego po poprzednim dostawcy zwykle oznacza więcej niż samo przekazanie plików. Nowy zespół musi poznać rzeczywisty stan systemu, odzyskać potrzebne dostępy i odtworzyć kontekst, którego wcześniej nikt nie zapisał.

W takiej sytuacji dokumentacja powstaje częściowo jako efekt poznawania systemu. Najpierw trzeba ustalić fakty. Dopiero później można je sensownie uporządkować.

Podsumowanie

Dobra dokumentacja projektu IT nie powinna być mierzona liczbą stron. Jej wartość widać wtedy, gdy ktoś nowy musi zacząć pracę z systemem.

Dokumentacja powinna wyjaśniać cel produktu, procesy biznesowe, kluczowe funkcje, architekturę, wcześniejsze decyzje oraz znane ograniczenia. I musi rozwijać się razem z produktem.

Jeśli nowa osoba może zrozumieć podstawy systemu bez wielogodzinnego wypytywania jego autorów, dokumentacja spełnia swoją rolę.

Jeżeli większość wiedzy nadal trzeba zdobywać od „właściwej osoby”, warto ją uporządkować, zanim ta osoba przestanie być dostępna.