Dokumentacja to jeden z ważniejszych elementów pracy programistów!

Zupełnie przypadkiem odkryłam, że pisanie dokumentacji i budowanie kultury w zespole wokół tworzenia dokumentacji to “mój konik”. Kiedy w moim rocznym podsumowaniu obok projektów programistycznych, każdy mój współpracownik wymienił właśnie to. Okazuje się, że temat dokumentacji jest strasznie ciężki dla programistów – często traktowana jest ona “po macoszemu” i zbywana komentarzami w stylu “piszę mój kod tak klarownie, że nie potrzeba już więcej objaśnień!”. Ja jednak twierdzę, że dokumentacja jest jednym z ważniejszych elementów pracy programisty i programistki, i w tym tekście opowiem Ci, dlaczego warto pisać dokumentację.
 

Dlaczego warto pisać dokumentację?

Tworzenie dokumentacji powinno być nieodłącznym elementem pracy programistów. Zaczynając od pracy nad projektem programistycznym, powinniśmy najpierw opisać projekt na papierze, rozważając jego poszczególne elementy i dzięki temu podejmując lepsze decyzje projektowe. W późniejszej fazie pracy ważne są komentarze w kodzie – takie, które mówią o tym, co dana funkcja robi i jak jej używać. Na koniec nie można też zapomnieć o stworzeniu dokumentacji dla użytkowników, czy innych zbiorczego dokumentu podsumowującego projekt i służącego za dobry punkt wyjścia dla osób, które w przyszłości nad naszym projektem będą pracować.
 
Brzmi jak strasznie dużo roboty, prawda? I pewnie też dlatego wiele programistów nie cierpi pisać dokumentacji – traktując ją jak jeden ze znienawidzonych obowiązków domowych, z lekkim przymrużeniem oka, pisząc ją raczej niedbale i byle jak. Jednak naprawdę warto pisać dokumentację, ot z tych kilku powodów:
 
Po pierwsze – za pół roku nie będziesz pamiętać, co chciałaś osiągnąć w danej linijce!
Programiści mają to do siebie, że w ciągu roku piszą bardzo dużo kodu, a ich umiejętności ciągle się szlifują – kod pisany pół roku wcześniej z reguły prezentuje się znacznie gorzej niż ten pisany teraz. Jednocześnie, praca programisty wiąże się z tym, że pracujesz nad różnymi projektami, w różnej fazie. Nie ma szansy, że po pół roku będziesz wiedzieć, o co chodzi w danej linijce kodu! Tym bardziej, jeśli spod Twoich palców wyszedł tzw. spaghetti code! (Nie ma co się tego wstydzić, każdy ma gorszy dzień).

Dlaczego warto pisać dokumentację_ - małe grafiki (2)
Dlatego też pamiętaj, że jednym z powodów tworzenia dokumentacji, jest pisanie jej dla siebie samej.
 
Po drugie – chcesz, żeby z Twojego projektu korzystali też inni…
Dokumentacja użytkownika jest niesamowicie istotna! Jeśli chcesz, żeby ktoś korzystał z Twojej pracy – to musi wiedzieć jak. Pomyśl teraz o grach planszowych – autorzy gier piszą naprawdę świetne instrukcje, tak by każdy, kto zainwestuje w ich grę, był w stanie przeczytać i zrozumieć, o co chodzi. I Twój projekt programistyczny również powinien dostarczać użytkownikom równie klarowne instrukcje.
 
Dobrze napisana dokumentacja użytkownika, to również oszczędność Twojego czasu, gdyż dzięki temu nie musisz wielokrotnie odpowiadać na te same pytania skonfundowanych userów. Zwyczajnie odsyłasz ich do odpowiedniego miejsca w dokumentacji, gdzie znajdą wszelkie informacje, wskazówki i przykłady.
 
Po trzecie – nie chcesz w nieskończoność być samotną wilczycą programistyczną…
Projekty programistyczne mają to do siebie, że im większe, tym więcej rąk do pracy potrzeba, aby je utrzymać i rozwijać. Pracując w firmie programistycznej, raczej na pewno będziesz pracować w grupie osób. I owszem – jest spora szansa, że podzielicie jeden projekt na mniejsze części i Ty będziesz zajmować się czymś zupełnie innym niż Twój kolega czy koleżanka z zespołu, ale prawie na pewno w którymś momencie będziecie musieli pracować wspólnie. I właśnie na takie sytuacje dobrze mieć dokumentację wewnętrzną, czyli taką, która pokrótce przeprowadzi innych programistów przez sam projekt i najważniejsze decyzje projektowe do tej pory podjęte, oraz pozwoli im szybko wdrożyć się w temat i zacząć produktywnie pracować.
 
Po czwarte – bo chcesz się rozwijać!
Bycie “zwykłym klepaczem kodu” jest bardzo satysfakcjonujące, jednak to dopiero początek drogi w karierze programistki. Kolejnym etapem jest praca tzw. Tech Leada (lub Team Leada), czyli bycie liderem zespołu programistów. Wiele TLów wpada często w pułapkę – wciąż próbuje pisać kod, jednocześnie starając się ogarniać zespół “świeżaków”, czyli programistów na wcześniejszym etapie kariery, którzy mają mniej doświadczenia i często potrzebują pomocy w nawigowaniu swoich obowiązków. Wtedy właśnie okazuje się, że TL nie potrafi się rozdwoić – a skoro całą swoją wiedzę ma zapisaną w głowie, zespół nie może posunąć się dalej bez pomocy swojego lidera. 
 
Dlatego też dobrze jest dokumentować swoje projekty, decyzje projektowe, a nawet najczęściej zadawane pytania – bo dzięki temu oszczędzasz swój czas, oszczędzasz też czas swojego zespołu, pozwalasz użytkownikom na pełne wykorzystanie tworzonych przez Ciebie narzędzi, a także wspierasz swój własny rozwój, sprawiając, że Twój zespół nie jest 100% od Ciebie zależny!
 

Jak pisać dokumentację – czyli jak robić, żeby się nie narobić?

Wiemy już, że pisanie dokumentacji jest ważne, ale pisałam też o tym, że to jedno z najbardziej nielubianych zadań wśród programistów. Jak zatem podejść do pisania dokumentacji tak, żeby stało się to przyjemnością?
Dlaczego warto pisać dokumentację_ - małe grafiki (1)
Automatyzuj!
Jesteś programistką, stąd pewnie przywykłaś już do tego, że jeśli coś Ci się nie podoba, albo niektóre czynności są powtarzalne i żmudne – starasz się je automatyzować. To samo możesz zrobić z dokumentacją! Dostępnych jest wiele różnych narzędzi, które przetwarzają Twój kod i komentarze do funkcji, klas i metod, a następnie wypluwają czytelny i odpowiednio sformatowany tekst, który możesz następnie wykorzystać na stronie swojego projektu. 
 
Pisania komentarzy do kodu raczej nie da się wyeliminować, możesz jednak zadbać o to, by każdy commit był sprawdzany przez odpowiedni linter, który zweryfikuje, czy wszystkie publiczne funkcje są opatrzone odpowiednim komentarzem i jeśli tak nie jest – zwróci odpowiedni komunikat.
 
Pisz tak, jakbyś tłumaczyła pracę młodszemu rodzeństwu!
W dokumentacji wcale nie chodzi o to, żeby wykazać się ogromną elokwencją i wykorzystywać możliwe najtrudniejsze sformułowania do opisania danego programu, czy wybranego rozwiązania. Co więcej, tego typu tekst w rzeczywistości jeszcze bardziej utrudnia zrozumienie problemu! Dlatego też lepiej korzystać z możliwie prostych opisów, bez zbędnych utrudnień – tak, jakbyś tłumaczyła swoją pracę młodszemu rodzeństwu czy rodzicom, bądź po prostu osobie, która dopiero dołącza do zespołu i nie ma żadnej wiedzy na temat danej technologii czy projektu.
 
Moim zdaniem w im prostszy sposób potrafisz wytłumaczyć, co robi Twój kod i jak z niego  korzystać, tym bardziej efektywna jest Twoja dokumentacja i tym większą wartość niesie dla przyszłych czytelników!
 
Pisz, zanim jeszcze zaczniesz programować…
Część dokumentacji – zwłaszcza informacje o rozważanych i wybranych rozwiązaniach oraz opis, dlaczego dane decyzje zostały podjęte – dobrze opisać, zanim zaczniesz programować. 
Dlaczego warto pisać dokumentację_ - małe grafiki
Wiele pomysłów świetnie wygląda w Twojej głowie, ale kiedy poświęcisz im dłuższą chwilę i opracujesz odpowiedni design doc, dajesz sobie szansę na lepszą analizę problemu, zauważenie dodatkowych corner cases (zanim jeszcze okaże się, że niezauważone wylądują na produkcji i popsują Twój serwis…), a przede wszystkim – zyskujesz możliwość konsultacji proponowanego rozwiązania z innymi programistami! Po przeczytaniu takiego dokumentu mogą oni zwrócić Ci uwagę na dodatkowe zagadnienia, które Tobie wcześniej umknęły i podpowiedzieć, jak jeszcze można podejść do rozwiązania. Dzięki temu Ty uczysz się i rozwijasz, a ponadto oszczędzasz dużo czasu, tworząc od początku bardziej przemyślanie rozwiązanie.

Elementy dobrej dokumentacji…

…użytkownika
Zadaniem dokumentacji użytkownika jest przedstawienie Twojego programu potencjalnym użytkownikom, opisanie jaki problem rozwiązuje i jak używać tego narzędzia. Warto więc zacząć od streszczenia informacji o projekcie – do czego służy Twój program, skąd można go pobrać, i jak zacząć. Następnie warto w bardziej szczegółowy sposób opisać sposób działania Twojego kodu – jeśli jest to biblioteka, którą wykorzystywać mogą inni programiści, dodaj informacje o tym, jak szybko działa i jak bardzo obciąża pamięć. Koniecznie dodaj też sekcję o wymaganiach, tzn. jakie dodatkowe biblioteki, czy pakiety konieczne są, żeby uruchomić Twój program, czy zadziała on równie dobrze na różnych systemach operacyjnych etc.
 
Kolejnym ważnym elementem dokumentacji użytkownika są przykłady użycia. Podaj przykładowe sytuacje, w jakich można wykorzystać Twój program i jak to zrobić. Jeśli trzeba, załącz przykładowy kod i dokładnie opisz wszystkie parametry, które można sprecyzować.
 
Na koniec dopracuj sekcję najczęściej zadawanych pytań, w której systematycznie będziesz zbierać kolejne przykłady i odpowiedzi na pytania. Twoja dokumentacja powinna również zawierać informacje kontaktowe – w wypadku problemów, czy pytań, użytkownicy muszą wiedzieć, jak należy Cię powiadomić – czy będzie to mail, czy wiadomość na forum, warto sprecyzować ten kanał i odsyłać do niego z dokumentacji.
 
…wewnętrznej (lub developerskiej)
Dla devów w zespole, który współtworzy dany produkt, dokumentacja użytkownika stanowi pewną podstawę, jednak warto wypracować w zespole kulturę pisania dokumentacji. Komentarze w kodzie, choć są istotne, to jednak nie są wystarczające. Zacznij od stworzenia “quick start guide”, czyli krótkiego poradnika, który pozwoli osobie niezaznajomionej z projektem w krótkim czasie zacząć efektywnie pracować. Poradnik może zawierać odnośnik do wcześniejszego design doc, czy jakiegokolwiek wcześniejszego researchu, który być może Twój zespół wykonał. Nie zapomnij opisać również zastosowanych rozwiązań i ich konfiguracji oraz jak współgrają z Twoim kodem. 
 
Ważnymi elementami wewnętrznej dokumentacji są również:
  • odnośniki do tzw. entry points kodu źródłowego (np. do zaimplementowanych bibliotek, czy kodu głównego programu);
  • odnośniki do unit testów i testów integracyjnych wraz z informacją, jak najlepiej je wykonać;
  • informację o dostępnych narzędziach (wszelkie narzędzia przydatne w debugowaniu, informacje, gdzie można znaleźć logi programu itd.);
  • listę potrzebnych narzędzi oraz dodatkowe pliki konfiguracyjne przydatne podczas pracy;
  • code style, czyli plik opisujący styl, w jakim dany kod powinien być utrzymany (np. czy klamry zaczynają się w nowej linii oraz czy używane są spacje, czy taby…);
  • opisy potencjalnych błędów (jeśli istnieją znane już błędy i sposoby ich tymczasowego rozwiązania, to warto o nich wspomnieć – nie chcesz przecież, żeby każdy od nowa spędzał swój cenny czas, debugując kod);
  • jak wygląda deployment i inne operacje związane z utrzymaniem kodu!
 
 

Narzędzia przydatne w tworzeniu dokumentacji.

Poniżej znajdziesz listę narzędzi, które mogą przydać Ci się podczas pracy nad dokumentacją użytkownika, dokumentacją wewnętrzną bądź pisaniem design doców.
 
  1. Github wiki – uwielbiany przez programistów serwis daje możliwość łatwego tworzenia stron wiki do projektów. Pozwala w prosty sposób formatować tekst i linkować do poszczególnych stron i repozytoriów oraz jest bardzo łatwy w utrzymaniu, a przede wszystkim – stanowi nieodłączoną część repozytorium projektu. Nadaje się dobrze do pisania dokumentacji użytkownika bądź tej wewnętrznej, dla developerów pracujących nad danym projektem.
  2. Github pages – dla rozbudowanych projektów, github udostępnia również inną opcję – mianowicie daje możliwość tworzenia stron lądowania projektów, w których również w łatwy sposób można dodać dokumentację dla użytkowników.
  3. ReadTheDocs – to świetne narzędzie do generowania dokumentacji na podstawie komentarzy w kodzie. Tak stworzony dokument można następnie czytać w różnych formatach – HTML, PDF, a nawet w formacie przyjaznym czytnikom! Co więcej, narzędzie to pozwala na zapisanie kilku wersji dokumentacji, co świetnie sprawdza się w projektach, których różne wersje ewoluują i nie wszystkie opcje dostępne są w każdej z nich.
  4. NaturalDocs – jest kolejnym narzędziem służącym do generowania dokumentacji na podstawie specjalnie sformatowanych komentarzy. Generuje przejrzysty HTML i jest dostępny dla 21 języków programowania (ale możesz samodzielnie rozbudować go o kolejne!).
  5. Dropbox Paper – Paper świetnie nadaje się do prowadzenia wewnętrznego wiki! Pozwala na łatwe formatowanie (markdown), szybkie tworzenie nowych dokumentów i linkowanie do innych, grupowanie dokumentów w folderach oraz wyszukiwanie po tagach. Paper świetnie sprawdza się jako narzędzie do tworzenia dokumentacji również dlatego, że umożliwia dodanie zadań wewnątrz plików oraz oznaczenia osób odpowiedzialnych, czy też wspiera kolaborację wielu autorów jednocześnie i późniejsze komentowanie powstałego pliku. 
 
Co więcej, jeśli chcesz dowiedzieć się więcej na temat pisania dokumentacji, to zachęcam Cię do dołączenia do społeczności Write The Docs, która zrzesza pasjonatów tego zagadnienia! W sierpniu i później na jesieni tego roku planowane są konferencje poświęcone ściśle pisaniu dokumentacji!
 
I nie przejmuj się, jeśli Twoi znajomi będą z przekorą nazywać Cię bibliotekarką. Przypomnisz im o tym, jak następnym razem poproszą Cię o pomoc przy pracy nad dokumentacją ich własnego projektu…