Dokumentacja możliwa do utrzymania

Całe moje zawodowe życie, stykam się z problemami utrzymania dokumentacji. Zwykle brakuje czasu na jej aktualizację a jak już się znajdzie to i tak już nikt nie pamięta co było zmieniane więc nikomu się już nie chce tego uzupełniać bo trzeba by robić analizę kodu. Pozostaje więc dziurawa pamięć plemienna a jeżeli takiego szamana nie ma pod ręką to zaczyna się bieda. Trzeba analizować kod, szukać ludzi po git blame. Zajmuje to dużo czasu i zwykle i tak wielu rzeczy się nie pamięta.

Postanowiłem więc ukrócić (przynajmniej częściowo) te problemy i zacząłem wdrażać nowy model dokumentacji. Podzieliłem ją na 3 obszary: główna dokumentacja architektury, zgrubna dokumentacja aplikacji i dokumentacja techniczna.

Główna dokumentacja architektury zawiera się w CMDB oraz w grafach przedstawiających ją z lotu ptaka. Pozwala to na stosunkowe łatwe i rzadkie do zmiany utrzymanie. Przecież niezbyt często dodajemy nowe aplikacje. Tutaj jest prosto więc w sumie nie ma za bardzo nad czym się rozwodzić.

Problem zaczyna robić się przy zgrubej dokumentacji aplikacji. Tutaj znowu jest problem z jej utrzymywaniem, więc w duchu agile jest ona raczej mało rozbudowana i zawiera najważniejsze case'y czy procesy. Jest to dokumentacja raczej biznesowa niż techniczna, więc to na niej pracuję wspólnie z interesariuszami. W dużej części to właśnie po stronie biznesu jest utrzymanie dokumentacji. Oni zgłaszają zmiany w funkcjonalnościach i procesach, więc w ramach analizy opisuje zmiany. Jest to najbardziej klasyczna dokumentacja ale bez niej ciężko by było prowadzić jakiekolwiek prace. Najważniejsze w procesie zarządzania dokumentacją

Najważniejszą dla mnie jest dokumentacja techniczna. To właśnie ona zawiera technikalia oraz informacje o dokładnych funkcjonalności. Aplikacje jakimi się zajmuję w aktualnej pracy to serwisy wystawiające API, więc jego dokumentacja opisane w openAPI/Swager jest dokładną dokumentacją funkcjonalności jakie mamy w aplikacji więc w połączeniu z grafami przedstawiającymi powiązania z innymi aplikacjami daje solidną wiedzę na temat tego co aplikacja robi i dla kogo. Ale w technicznej dokumentacji mam jeszcze ADR, czyli Architecture Decision Record. Wdrożone według templatu Michaela Nygarda. Zapisujemy w nich najważniejsze zmiany i decyzje związane z aplikacją jakie podejmowane są przez zespół w kontekście pisanego kodu.