Nagle słyszę: "Ręce z kieszeni - dokumenty!"

Odwracam się, a to szef cały spięty

Nikt nie ma dokumentów, bo nikt nie jest …

Gdy widzę projekt tworzenia oprogramowania, w którym nie ma dokumentacji, to prędzej czy później dopłynie on do swojej góry lodowej, czyli konieczności wprowadzenia większych lub nawet mniejszych zmian, a ja wtedy na spokojnie już mogę tylko dokończyć cytatem z tej samej piosenki:

Ja wiedziałem, że tak będzie ...

Dlaczego nikt nie pisze dokumentacji?

Dzieje się tak najczęściej dlatego, że ludzie wierzą w często powtarzane mity i legendy odnośnie tworzonego oprogramowania:

1. Kod jest samodokumentujący się

Kto czytał kod realizujący nawet proste zadanie, ale napisany niechlujnie, albo kod jest nieczytelny (celowo lub przypadkowo), ten wie, że czasami przypomina to robotę egiptologów próbujących rozszyfrować hieroglify.

2. Kod jest lepszy od najlepszej dokumentacji, bo jest aktualny

Jeśli programiści nie utrzymują higieny (nie osobistej, mam nadzieję ten stereotyp już dawno obalony), tylko higieny kodu, czyli jeśli nie usuwają nieużywanych fragmentów, nie aktualizują komentarzy, to patrz punkt pierwszy.

3. Programista po trzech, czy sześciu miesiącach od niepatrzenia na kod dalej pamięta, po co powstał dany moduł i dlaczego zostało napisany w ten a nie inny sposób

"Pamięć absolutna" to tylko tytuł filmu. W prawdziwym życiu, gdzie z jednego projektu płynnie przechodzi się w następny, nierzadko biorąc udział w tworzeniu więcej niż jednego rozwiązania równolegle poleganie tylko na pamięci programisty jest mocno ryzykowne.

4. Biznes wie, co robi system, bo przecież zgłaszali wymagania

Po stronie biznesu, tak jak po stronie zespołu programistycznego zachodzą zmiany w składzie osobowym. Ludzie miewają dłuższe przerwy od zajmowania się danym projektem i tak jak w przypadku programisty, który patrzy na kod zastanawiając się: "co za ojciec muła to napisał" (podczas, gdy był to on sam), tak samo pamięć osób zgłaszających wymagania jest niedoskonała i nie muszą trzymać kontekstu "do końca świata i jeden dzień dłużej".

5. Biznes wie, jakie procesy ma wspierać system, bo przecież w nich uczestniczą

Może i wie w jakich procesach uczestniczy, ale nie koniecznie obchodzi daną osobę coś poza jej wycinkiem. Może nie potrafi spojrzeć na swoje działanie w formie procesu. Może proces jaki jest realizowany z wykorzystaniem narzędzia softwareowego nie wygląda do końca tak jak był projektowany i jak został zaimplementowany (historia zna niezliczone przypadki, gdy oprogramowanie jest wykorzystywane nie do końca zgodnie z przeznaczeniem).

Oprócz ww. błędnych założeń odnośnie obiegu wiedzy o systemie, to braki w dokumentacji biorą się często z jednego prozaicznego powodu - nikt nie jest odpowiedzialny za to, żeby dokumentacja nie tylko powstała, ale była na bieżąco aktualizowana z każdymi kolejnymi zmianami w procesie.

To jak podejść do tworzenia dokumentacji w projekcie software'owym?

W dwóch słowach to "temat rzeka", ale spróbuję go streścić.

Wbrew pozorom i ogólnej niechęci do "projektowej beletrystyki" warto przyjąć zasadę, że jeśli nie ma czegoś w "papierach", to nie ma tego w systemie. A "w papierach" mam na myśli centralne repozytorium wiedzy o rozwiązaniu, do którego wszyscy mają dostęp i które wszyscy zasilają aktualnymi informacjami (jakieś wiki, czy inny sharepoint).

Zasada - "najpierw papier później kod" może wymaga więcej wysiłku w danym momencie, ale ułatwia długofalową współpracę między biznesem, a zespołem developerskim i pozwala w bardziej przewidywalny sposób rozwijać i utrzymywać system. Już nie mówiąc o możliwości przemyślenia w trakcie pisania, czy to co chcemy zrobić ma sens.

UWAGA: Maile zazwyczaj słabo działają jako "repozytorium" wiedzy, bo mają tendencje do bycia kasowanymi, adresowanymi nie do tych osób co potrzeba, etc. Dodatkowo, ponieważ dziennie ludzie otrzymują od kilkudziesięciu do kilkuset maili, z nierzadko sprzecznymi informacjami odnośnie jednego tematu, to oczekiwanie, że ktoś będzie pamiętał co wysłałeś w "przed-przedostatniej" wiadomości i że to było to najbardziej wiążące ustalenie jest proszeniem się o kłopoty.

Rozwiązania robione "na gębę" są "ulotne jak ulotka". Znaczy jakoś działają, ale dlaczego tak i czy to jest zgodne z planem, to tego nikt już nie wie. Jeśli chcesz te "ulotne chwile łapać jak fotka", to usiądź przed Confluencem, czy innym Wordem i napisz co ten system ma robić (biznes) i jak to zostało zrobione (IT).