Krótki tekst o dokumentacji

Ten tekst będzie o tym co warto dokumentować i jak to robić – oczywiście z bardzo subiektywnego punktu widzenia(!). No i o tym, że wcale nie zawsze potrzebujemy dokumentacji – a wręcz czasem najlepsze co możemy zrobić to skasować istniejące dokumenty! Ale po kolei. Zanim dotrzemy do rozwiązania, musimy najpierw spojrzeć na przyczyny i źródła zamieszania…

Moje dotychczasowe doświadczenia (i nie tylko moje) pokazują, że ludzie niezadowoleni z poziomu udokumentowania swojego systemu/projektu są raczej w większości. Z drugiej strony w wielu osobach tkwi silne przeświadczenie, że dokumentacja musi być i trzeba ją mieć, bo jak się jej nie ma to jest bardzo źle. Przez to wszystko, jednym z częstszych problemów z którymi borykają się projekty jest coś w rodzaju mitologiczno-romantycznej tęsknoty za światem idealnej dokumentacji i chaotyczne próby dotarcia do tego świata.

Jest to naprawdę piękny świat. W tym świecie mamy taką dokumentację co to ją damy każdemu nowemu człowiekowi i znajdzie tam odpowiedzi na wszystkie pytania. No i taką co to w przypadku problemów, awarii, zwiększenia ruchu, nagłej zmiany wymagań, ataku hakerów, uaktualnienia middleware’u  albo bazy danych da nam „odpowiedzi”. W końcu te wszystkie nowe wymagania też dokumentujmy tak, że jak byśmy dali te dokumenty dwóm różnym zespołom to by zrobili dokładnie to samo. Ba! Nie zadawaliby żadnych pytań, bo wszystko będzie w dokumencie. Wszystko… a więc opisy, diagramy, wykresy, analizy, pomysły, uwagi, ostrzeżenia, złe i dobre praktyki, standardy.

Ten świat zasadniczo nie ma aż tak dużo wad. Co prawda taki dokument prawdopodobnie może być dość długi. No prawdę mówiąc nawet słowo „dość” jest tutaj lekko nie na miejscu, podobnie jak słowo „długi”. Lepsze byłoby za pewno „długaśny” albo „przeolbrzymi”. Co więcej mając wiele takich dokumentów trochę trudno znaleźć ten, który akurat jest nam potrzebny. Na szczęście nie trzeba się nad tym za bardzo zastanawiać, bo jakkolwiek by tego nie nazwać, świat idealnego dokumentu (tak jak większość światów idealnych) nie istnieje, co jest jego ewidentną zaletą. Niestety jednak, kolejną cechą idealnych, nieistniejących światów jest to, że jest sporo ludzi, którzy za wszelką cenę odrzucają to nieistnienie. No bo przecież gdzieś tam, za zielonymi wzgórzami i wielkim morzem na pewno piszą świetne dokumenty… Na pewno.

Efektem tej wiary w istnienie ideału są próby dążenia do niego. Zapewne każdy z programistów prędzej czy później zetknie się z takim „prorokiem” idealnej dokumentacji, który będzie głosić, że „znamy kierunek w którym trzeba podążać – idźmy więc!”. Jeśli będzie to inny programista – czy ogólnie kolega z zespołu to nie jest jeszcze aż tak źle. Gorzej, jeśli trafi się nam mandżer lub klient, który wyznaje tą dziwaczną „religię”. Co wtedy się dzieje?

Ponieważ (wbrew pozorom) informatycy z reguły nie są głupi – nasi wyznawcy super dokumentów zaczynają kojarzyć pewne fakty. Fakt 1: póki co nie mamy dobrej dokumentacji, fakt 2: musimy ją mieć, fakt 3: trzeba zacząć jak najszybciej. Konsekwencją tych faktów jest często narzucenie obowiązku bardzo szczegółowego opisywania (nierzadko w oparciu o jakieś mądre standardy) tego co akurat robimy. Czyli na przykład – nie mamy nigdzie opisanej architektury systemu, ani chociażby modelu danych, którymi operujemy, czy chociażby najważniejszych bytów w bazie danych – ale dodanie nowej, losowo wybranej (i być może zupełnie mało ważnej) kolumny do bazy danych wymaga od nas wypełnienia kilku stron formularzy. Oczywiście większość pól w takim formularzu wypełniamy tekstem „N/A” albo „nie dotyczy” – ale mimo wszystko robimy to. Najprostsza zmiana otrzymuje dokument. Bardziej skomplikowane zmiany też. No i różne inne czynności – ważne i nie ważne również. Nasz „prorok” jest zadowolony – w końcu ilość dokumentów przyrasta. Co więcej można poświęcić etat lub dwa na weryfikowanie czy: a) podwładni przestrzegają restrykcyjnych obowiązków dokumentowania (i wymierzać kary jeśli nie), b) akceptować dokumenty (a nie ma zbyt wielu fajniejszych zadań niż akceptowanie cudzych dokumentów… no może poza odrzucaniem cudzych dokumentów;), c) składować zaakceptowane dokumenty, d) pisać nowe dokumenty o tym jak pisać dobre dokumenty, e) pisać nowe dokumenty o tym dlaczego ludzie nie piszą dokumentów i dlaczego niektóre z nich trzeba było odrzucić, f) pisać kolejne dokumenty o tym jak wygląda proces dokumentowania i jak go poprawić. I tak dalej i tak dalej.

Krótko mówiąc, maniakalne podejście do dokumentacji, polegające na zmuszaniu ludzi do tworzenia dokumentów w losowych (lub we wszystkich) przypadkach w środku (lub nawet na początku) projektu z reguły prowadzić do… powstania masy dokumentów, które w większości są bezużyteczne (pomijając oczywiście bardzo ważny użytek jaki robi z nich osoba akceptująca je – w końcu dzięki temu ma prace).

W takich chwilach zawsze odgrzewam sobie w głowie pojęcie „wartości intelektualnej dokumentu”. Trudno zdefiniować co to jest, ale wyobrażam sobie, że w jakiś sposób każdemu tekstowi, który muszę przeczytać da się przypisać liczbę. Liczba ta mierzy jak bardzo zmądrzałem po przeczytaniu danego tekstu – ile mi to dało. Jest to naprawdę przydatny sposób myślenia – szczególnie jeśli uwzględnimy, że ta liczba może (i często bywa) ujemna.

Dokumentowanie „na hura” byle czego skutkuje powstawaniem masy dokumentów o ujemnej wartości, co nie wydaje się niczym zaskakującym. Niestety warto o tym wspomnieć, bo wciąż takich dokumentów przybywa.

Co więc robić? Najlepiej by było, usiąść na spokojnie i zastanowić się co warto udokumentować w pierwszej kolejności i jak bardzo szczegółowo to robić. Stworzyć plan z założeniami i planowanym rezultatami i sposobami pomiaru jakości. O tak… i kilka(naście) spotkań na ten temat. Puk, puk! Kilka paragrafów wcześniej pisałem o surrealistycznych, idyllach – światach idealnych w których mamy czas i siły robić te wszystkie rzeczy, które powinny być zrobione żeby było idealnie :) Ten konkretny przykład to świat „najpierw wszystko idealnie zaplanujmy a potem idealnie zrealizujmy idealny plan”. W skrócie – nie da się.

Nie da się opisać wszystkiego, nie da się idealnie opisywać, nie da się nawet idealnie zaplanować co opisywać a co nie i jak. To co się da? I to jest moment w którym szczególnie programiści (lub byli programiści) powinni odwołać się do swojej wiedzy fachowej i przywołać dwa skojarzenia: wzorce projektowe i przetwarzanie iteracyjne (lub inkrementalne lub jeszcze lepiej algorytmy genetyczne).

Wzorce projektowe – dlatego, że nie wszystko musimy wymyślać od początku od zera. Można wyróżnić kilka wzorców i kilka antywzorców dokumentacyjnych. A iterowanie / algorytmy genetyczne dlatego, że nie wszystko musi nam pasować. Szczególnie nie każdy znany i podziwiany przez innych wzorzec jest dobry dla nas. Czyli startujemy z jakiegoś punktu opartego na kilku wskazówkach – opisanego krótko i zwięźle, co i kiedy warto opisywać… i testujemy nasze podejście wciąż je oceniając i dostrajając.

Jak zacząć? Tak jak wspomniałem we wstępie – to jest mocno subiektywne spojrzenie. Moja „recepta” wcale nie jest najlepsza i jedyna. Ale ja radziłbym na początek przyjąć takie założenia:

1. Nie ma nic gorszego niż nieaktualna dokumentacja. Jeśli nie masz możliwości zaktualizowania dokumentu – skasuj go (lub przynajmniej wyraźnie oznacz „NIEAKTUALNE – NIE CZYTAĆ”). Dlaczego? Bo znajdzie się ktoś, kto przeczyta ten tekst i zmarnuje czas, następnie zajrzy w kody, albo do bazy, albo uruchomi aplikacje… i w optymistycznym przypadku szybko zauważy, że zmarnował czas. A w pesymistycznym? Może brnąć w jakiś ślepy zaułek. Gdyby nie było dokumentu sprawa byłaby jasna – trzeba przeczytać i zrozumieć kod, który nie może być nieaktualny o ile działa.
2. Jeśli nie jesteś pewien czy pisać dokument czy nie – to nie pisz. Naprawdę nie chcesz mieć dokumentów o ujemnej wartości intelektualnej – bo od tego Ty i twoi współpracownicy zgłupiejecie! Co więcej – jeśli jesteś pewien, że dokument nie jest potrzebny a ktoś zmusza Cię, żebyś go napisał tylko dlatego, że być on musi – to skorzystaj z jakiegoś generatora bełkotu, albo przeklej poprzedni dokument nad którym pracowałeś. Jednym słowem nie marnuj czasu;). W najgorszym wypadku dostaniesz tekst do poprawki. A w najlepszym zyskasz kilka godzin/dni/tygodni!
3. Jeśli robisz coś zupełnie standardowo tak jak w większości tego typu projektów – nie opisuj tego. Jeśli rozwijasz produkt w oparciu o jakąś typową technologię typu Java EE, Spring, .NET, Ruby on Rails, to nie musisz od razu pisać podręcznika o tej technologii. Jedyne co warto zrobić to wypunktować technologie, które są używane.
4. Jeśli jakaś koncepcja, konwencja, pomysł powtarza się w wielu miejscach – to opisz i nazwij tą koncepcje – nie opisuj oddzielnie każdego jej wystąpienia. Być może w każdej tablicy w twojej bazie danych jest kolumna ID, albo być może CU_ID zawsze oznacza identyfikator klienta, albo wszystkie klasy kontrolerów nazywają się *Controller i są w pakiecie pl.trzeciakawa.Controllers. Być może dostęp do bazy danych robi się przez klasy Repository*, które korzystają z Entity Framework… i tak jest zawsze. To opisz to zawsze, a nie konkretne podstawienia pod *. A jeśli w jakimś miejscu jest inaczej niż zawsze to właśnie to miejsce i tylko to zasługuje na dodatkowy opis.
5. Nadaj dobre nazwy – programowanie to sztuka nazywania rzeczy, czynności, osób. Opisz powszechnie używane nazwy. Programista jest trochę jak poeta. Tylko poeta stara się nazwać jedną rzecz tysiącem słów, a programista próbuje jedynym terminem objąć tysiące rzeczy. Za dużo już projektów się odbyło w których na klientów mówiono „Clients”, „Customers”, „Users”, „Members” zależnie od widzimisie autora. Po pierwsze primo pilnuj nazw. Po drugie każdą ustaloną nazwę warto spisać.
6. Trzymaj dokumentację blisko tego co opisuje. Jeśli to tylko możliwe to trzymaj dokumentację w tym samym miejscu co kod źródłowy. Wersjonuj ją tak samo i traktuj tak samo. Błąd w dokumentacji to coś jak błąd w kodzie – powoduje zamieszanie i opóźnia prace. Co więcej dostęp do informacji powinien być możliwie prosty – skoro mam kody/bazę to powinienem od razu mieć też dokument. (To nie znaczy, że nie można jej publikować gdzieś na wewnętrznym www/wiki. Jak najbardziej można – ale nie powinien być to „odrębny produkt”.)
7. Pamiętaj, że najlepszą dokumentacją kodu źródłowego jego kod źródłowy sam w sobie a nie jego komentarze! Czasem słychać wypowiedzi w stylu: „niestety ten fragment nie jest udokumentowany, musisz zobaczyć w kodzie i zrozumieć jak działa”. To słowo „niestety” w wielu sytuacjach warto zastąpić przez „na szczęście”. Kod źródłowy jest dla ludzi nie dla maszyn. Maszyny, żeby go zrozumieć i wykonać muszą go sobie przetłumaczyć (po to są im kompilatory itd). Jeśli kod jest na tyle zawiły, że wymaga duże ilości komentarzy… to zamiast marnować czas na ich pisanie, lepiej pomyśleć nad refaktoryzacją kodu. A i jeszcze jedno – w ramach refaktoryzacji wyrzucaj zbędne komentarze!
8. Jeśli zrozumienie Twojego dokumentu zajmuje więcej niż zrozumienie tego, co ten dokument opisuje to wyrzuć dokument. W nawiązaniu do poprzedniego… Można napisać 10 stron tekstu o 5 linijkach kodu. Wszystko ok. Być może jest to uzasadnione. Ale w wielu przypadkach nie jest.
9. Jeśli nie wiesz od czego zacząć dokumentowanie swojego systemu/projektu napisz tekst „getting started” oraz opisz podstawowe założenia i cel tego co robisz. Getting started – czyli wprowadzenie do pracy dla nowych ludzi. Nie ma nic bardziej pożytecznego o ile tylko jest aktualne. Zwróci się przy przyjęciu pierwszej nowej osoby, a przy przyjściu 2,3,4,… będzie już tylko czysty zysk. Opisanie podstaw – ogólnego (!) pomysłu, założeń, narysowanie tego rysunku co to musisz go rysować wszystkim nowym ludziom, nazwanie wzorców, standardów i technologii które są używane – to praca, której efektem jest dużo więcej niż sam tekst.

A na koniec wróćmy do początku. Bo tak to jest na świecie, że aby coś dobrze zrozumieć trzeba się cofnąć do początku. A na początku całego pomysłu, że można opisywać systemy informatyczne był pomysł, że dzięki takiemu opisowi będzie nam łatwiej a nie trudniej.

Życzę wszystkim więcej dobrze udokumentowanych projektów, mniej bełkotu i bezdennie głupich stronic do przeglądania… i mam nadzieję, do przeczytania w kolejnych tekstach na Trzeciej Kawie. Ciekawe jaką wartość przypiszecie dla tego postu. Mam nadzieję, że jednak choć lekko dodatnią :)