Dokumentacja – od chaosu do bazy wiedzy

Podczas prezentacji, które prowadziłem na tegorocznym GeeCON-ie oraz na Forum Jakości, największe zainteresowanie uczestników wzbudził temat porządkowania i cywilizowania dokumentacji dla dużych systemów IT. Co naturalne, najbardziej tematem zainteresowani byli przedstawiciele firm, które pracują z dużymi systemami i w poprezentacyjnych rozmowach widać było, że wszyscy zmagamy się z bardzo podobnym problemem.

Każdy, kto pracuje z dużymi systemami bądź z systemami odziedziczonymi, zetknął się z sytuacją w której potrzebujemy zmienić jakiś komponent. Wiemy mniej więcej, do czego on służy, możemy z kodu mozolnie odcyfrować jak on działa – natomiast trudno jest uzyskać informację: dlaczego on tak działa, z czym jest połączony oraz jakie konsekwencje może mieć jego zmiana. Osoby, z którymi rozmawiamy o naszym problemie, rozkładają ręce i z przepraszającym uśmiechem mówią „no bo nasze systemy są kiepsko udokumentowane…”. Drugim ciekawym wyjaśnieniem jest powiedzenie „to wiedział Franek, ale on już u nas nie pracuje” – kolega Franek staje się wtedy mitycznym usprawiedliwieniem dla wielu braków. Jest to osoba ,która wszystko wiedziała, ale niestety odeszła z pracy, no co za pech…

Kiedy narzekania na brak dokumentacji osiągną pewną masę krytyczną, kiedy coraz więcej wpadek jest tłumaczonych przez brak wiedzy – ktoś światły podejmuje rewolucyjną decyzję „Musimy mieć dobrą dokumentację!”. Ale dokumentacji dla dużego systemu nie da się zrobić w trzy dni. Nie możemy zatrzymać na kilka miesięcy rozwoju systemu i zapędzić deweloperów do pisania dokumentów. Dlatego następne zarządzenie jest z reguły takie: „Od dzisiaj obowiązkowo dokumentujemy wszystkie nasze zmiany” – po czym od razu następuje pełne nadziei zdanie: „Jeżeli będziemy robić to konsekwentnie przed dłuższy okres czasu, to dorobimy się całkiem pokaźnej i wartościowej dokumentacji”. Czasami również ustanawiani sią Strażnicy Dokumentacji, czyli osoba lub zespół, którzy kontrolują, czy ta dokumentacja faktycznie powstaje. W jednej z dużych firm IT powstał kiedyś Zespół Zarządzania Dokumentacją, a skrót tego zespołu został niedługim czasie przez życzliwych kolegów rozwijany jako Zespół Zawracania Pewnej Części Ciała.

Problem polega na tym, że wydanie regulacji oraz ustanowienie Strażników Dokumentacji najczęściej wcale nie poprawia sytuacji! Po pewnym czasie dochodzi do tego, że faktycznie, projekty dostarczają jakieś dokumenty – ale użyteczność jest ich kiepska, jeżeli nie żadna. Dzieje się tak z kilku powodów.

Po pierwsze: każdy projekt tworzy swoją dokumentację. Jeżeli projekt A zmienia moduły X i Y, a projekt B zmienia moduły X i Z, to oba te projekty dostarczą zupełnie różną dokumentację modułu X. Czasami te dokumenty będą się pokrywały, a czasami będą opisywały moduł X z zupełnie różnych punktów widzenia.

Po drugie: mamy tylko dokumentację tych fragmentów systemu, które były dotknięte przez projekty. Jeżeli coś było używane przez lata, ale nie zmieniało – dokumentacji do tego nie ma. Możemy oczywiście posadzić kogoś i dać mu dwa tygodnie na wykonanie zadania „wykonaj ogólną dokumentację dla całego systemu”, ale mamy dużą szansę na to, że po roku rezultaty tej pracy będą nadawały się tylko do wyrzucenia.

I po trzecie: dokumentacja nie jest aktualizowana – bo któż i po co miałby to robić?

Po pewnym czasie uzyskujemy zatem zbiór niespójnych dokumentów, które opisują różne fragmenty systemu, robią to w różny sposób i są w różnym stopniu aktualne. Czy dziwi zatem, że ludzie nie korzystają z tej dokumentacji oraz nie lubią jej tworzyć?

Czy to można zrobić lepiej? W pewnym dziale IT pewnej organizacji udało się rozwiązać problem dokumentacji w troszeczkę lepszy sposób.

Pierwszą decyzją było oparcie dokumentacji o system wiki zamiast o zbiór luźnych dokumentów typu MS Word. Wiki ma parę ważnych zalet – można organizować dokumenty w drzewiastą strukturę. Można linkować dokumenty między sobą, co bardzo ułatwia poruszanie się i szukanie informacji. Można śledzić zmiany i wysyłać powiadomienia o zmianach. Ale – co najważniejsze – zmiana informacji w dokumencie jest dużo szybsza i bardziej naturalna niż w przypadku dokumentów przechowywanych w repozytorium. W przypadku dokumentu muszę pobrać dokument z systemu kontroli wersji, wykonać zmianę, oddać do systemu kontroli – i wciąż nie daje mi to gwarancji, że wszyscy użytkownicy tego dokumentu pobiorą i zobaczą zmienioną wersję. W przypadku wiki wykonana przeze mnie zmiana jest od razu widoczna dla wszystkich otwierających zmienioną stronę. Kolejnym plusem użycia wiki jest możliwość porównywania wersji między sobą oraz to, że nie potrzebujemy narzędzia zewnętrznego do aktualizacji dokumentacji – wystarczy nam do tego zwykła przeglądarka internetowa. Wiki także udostępnia nam bardzo użyteczną możliwość wyszukiwania pożądanych treści, nie tylko po tytułach dokumentów, ale również po ich zawartości oraz po treści zawartych w opisach rysunków – co bywa bardzo pomocne.

Drugim ważnym krokiem było stworzenie struktury dokumentacji, która mniej więcej odzwierciedlała strukturę istniejących systemów. Każdy system otrzymał niezależnie miejsce, w którym było miejsce na opis architektury tego systemu, miejsce na opis modułów, procedur, wchodzących zmian i innych elementów. Do tej struktury zmigrowano najważniejsze elementy istniejącej dokumentacji (migracja całości byłaby szalenie pracochłonna…), część stron zaś pozostała w stanie „uzupełnić później”. Oprócz zmigrowania istniejących dokumentów opisujących dany system, stworzono także miejsce, które wiąże ze sobą różne systemy, czyli opis usług biznesowych dostępnych dla biznesu. Co to znaczy? Każdy system ma swoją przestrzeń dokumentacji, ale istnieje jedno miejsce nadrzędne, które łączy dokumentacje systemowe i pokazuje jak działa dana usługa czy proces biznesowy.

Trzecim krokiem było powołanie osób, które zaczęły pełnić rolę Content Manager’ów. W każdym systemie istnieje tendencja do naturalnego wzrostu chaosu. Jeżeli stworzymy najpiękniejszą dokumentację i damy kilkudziesięciu ludziom możliwość swobodnego zmieniania jej – to już za chwilę dokumenty przestaną być spójne ze sobą, zaczną mieć różne formaty i będą umieszczane w losowo wybranych miejscach. Po części wynika to z niewiedzy ludzi, po części z istnienia różnych koncepcji, po części z lenistwa. Content Manager jest w pewnym sensie strażnikiem dokumentacji – ale nie strzeże tego, czy dokumentacja powstaje, lecz kontroluje formę tego, co powstało w jego obszarze. Może w powstającej dokumentacji poprawiać połączenia, przenosić ją w inne miejsce, sugerować zmiany oraz poprawki. W dziale IT wspomnianej organizacji Content Manager nie jest osobnym stanowiskiem, ale dodatkowym zadaniem niektórych osób. Bardzo ważne jest to, żeby Content Manager znał merytorykę systemu – dlatego przeważnie ta funkcja jest podzielona między wiele osób, z których każda nadzoruje tylko niewielki obszar dokumentacji. I ważne jest też to, aby była to osoba, która lubi porządek – przydzielenie tego zadania kreatywnemu artyście nie jest zbyt dobrym rozwiązaniem. Kolejnym zadaniem Content Managera jest stworzenie i uaktualnianie szablonów pod dokumentację. Dlaczego to jest ważne? Ponieważ jeżeli większość dokumentów wyglądała podobnie to łatwo i szybko jesteśmy w stanie znaleźć się pożądaną informację.

Kolejnym krokiem cywilizowania dokumentacji było ustalenie, że mamy jedno miejsce przetrzymywania dokumentacji w organizacji. Ilość systemów wpływa bardzo demotywująco na pracowników, ponieważ trzeba pamiętać, co gdzie trzymać i zapisywać. Dlatego stwierdziliśmy, że organizacja powinna dążyć do ujednolicenia przetrzymywania dokumentacji – czy to projektowej, czy technicznej. Każdy projekt powinien dokładać cegiełkę do istniejącej dokumentacji, a nie tworzyć swoją na swoje potrzeby.

Innym ważnym założeniem jest to, że dokumentacja powinna być łatwo dostępna, łatwo edytowalna oraz przeszukiwalna przez większość użytkowników (chociaż oczywiście istnieją wyjątki od tej zasady). Jeśli zabronimy edycji jakiś dokumentów, wpływa to demotywująco na osoby dodające wiedzę. Dobra baza wiedzy powinna dawać możliwość edycji większości informacji. Co to daje? Sprawia, że ludzie czują się ważni w procesie dostarczania informacji i popycha ich do dokładania kolejnych cegiełek. Nic tak nie motywuje jak to, że kolega dopisał coś fajnego – rodzi to reakcję: „ale przecież ja też coś wiem, też mogę się tym podzielić”.

Wszystkie powyższe kroki – wprowadzenie wiki, stworzenie struktury, powołanie Content Manger’ów i inne – tak naprawdę nie służą temu, żeby dokumentacja powstawała. Służą temu, aby dokumentacja była użyteczna. I tutaj dochodzimy do sedna tego artykułu: jedynym sposobem na dobrą dokumentację jest zadbanie o to, żeby była ona rzeczywiście użyteczna i przydatna w praktyce. Wtedy i tylko wtedy budzimy w pracownikach motywację do jej rozwijania. Jeżeli jestem deweloperem, jeżeli w mojej pracy znajduję potrzebne mi informacje w dokumentacji i jeżeli widzę, że ułatwia mi ona pracę – jestem zmotywowany do tego, aby ją rozwijać i aktualizować. Bo widzę cel tego działania, bo wiem że kiedyś wprowadzone przeze mnie informacje pomogą mi lub moim kolegom. Jeżeli piszę dokumentację, bo muszę to robić – zawsze będę robił to minimalnym kosztem, czyli byle jak.

„Informacja powinna szukać Ciebie, a nie ty powinieneś szukać informacji” – taka właśnie powinna być baza wiedzy w każdej firmie.

 Współautorem tego tekstu jest Maciej Szwalgin,
a oryginalnie został on opublikowany na portalu http://it-manager.pl/.