Cześć!

Od zeszłej niedzieli minęło raptem 8 dni. 8 dni od kiedy jadąc nocnym FlixBusem pisałem poprzedni Newsletter. Czuję się jakby minęły wieki, a w każdym razie co najmniej jeden. Nie wiem jak u Was, ale u mnie się działo!

Poniedziałek, wtorek SegFault. Mój debiut. Stresik był, niby występowałem już publicznie na meetupach i warsztatach, ale jednak to nie to samo. Publika, myślę koło 100 osób na sali. Ręce mi się trzęsły, głos się łamał, ale dałem radę. Bardzo się cieszę, bo dużo było pytań po wystąpieniu, osoby podchodziły i chwaliły. Odbiór był zaskakująco pozytywny. Najbardziej się cieszę, że widać, że ludzie byli zaciekawieni tematem, mówili, że nieco inna perspektywa przedstawiona i że byłem autentyczny w tym co mówię. Klawo! Jestem bardzo szczęśliwy z tego, że się udało.

Sama konferencja bardzo fajna, odświeżająca. Miałem już przesyt konferencjami, ale ta wróciła mi nieco wiarę. Dobre prelekcje, merytoryczne dyskusje, fajne afterparty. Wysoki poziom zarówno prelegentów jak i uczestników. Szczególnie dużo dyskusji było na drugi dzień, czyli tzw. Unconference, gdzie każdy mógł przykleić na ścianę temat, na który chciałby podyskutować i potem w podgrupkach następowała wymiana zdań. Właśnie jedna taka wymiana zainspirowała mnie do dzisiejszego tematu - a mianowicie dokumentacja projektowa. Chciałem pierwotnie pisać o zaletach mikroserwisów, skoro tak ostatnie 2 newslettery ponarzekałem o ich cięciu, ale dam odpocząć sobie i Tobie od tego, ale na pewno do tego tematu wrócę niedługo.

A więc dokumentacja projektowa! (a więc, nie zaczyna się zdania od a więc).

Żaden programista nie lubi tego robić - ja również! Nie ma nic gorszego niż siedzieć i “klepać dokumentację” pod koniec projektu. Rzadko w projektach udaje się utrzymać dokumentację choćby w zbliżonym do aktualności stanie. Mimo tego uwielbiam dokumentację, nie ma nic lepszego niż dobrze utrzymana dokumentacja gdy dołączasz do projektu. Co więcej nie ma nic lepszego niż dobra dokumentacja gdy wraca się do tematu, który robiło się kilka miesięcy wcześniej.

Chciałbym podać Ci parę pomysłów, które w moich projektach działają i może Tobie pomogą ją utrzymać:

1. Dokumentację trzymaj w repozytorium - żadne Confluence’y, żadne Sharepointy, żadne zasoby sieciowe - ino repozytorium! Najlepiej pisz ją w Markdown (pliki .md), upraszcza to znacząco zabawy z formatowaniem, pozwala czytać ją również z łatwością przez interfejs graficzny repozytoria (zarówno Github, Gitlab ją wspierają, również edycję online). Dodatkowo w przeciwieństwie do Worda ładnie widać diffy. Jeśli korzystasz z Github to za darmo uzyskasz też darmowy hosting. Jest również sporo narzędzi darmowych, które pozwolą Ci wygenerować statyczny html i hostować je u siebie w wewnętrznej sieci (Jekyll, GatsbyJS, Hugo, itd.). W Martenie tak właśnie robimy, używamy do generowania Storyteller, który również pozwala dynamicznie załączać do niej fragmenty kodu.
2. Włącz dokumentacje w proces Pull Requestów - Samo umiejscowienie dokumentacji z kodem tematu nie załatwi. Jaką to nam daje faktyczną przewagę nad wspomnianym Confluence? Trzymanie jej w repozytorium poza samym aspektem historycznym (git blame, te sprawy) pozwala też zweryfikować, czy zmieniany fragment ma odzwierciedlenie w dokumentacji. Dużo łatwiej jest to robić na bieżąco niż potem na hura na koniec. Dodatkowo uzyskujemy łatwą platformę gdzie możemy też widzieć historię dyskusji. Nie wiem czy to tylko ja, ale dla mnie komentowanie (szczególnie prowadzenie wątków dyskusji) na Confluence to tragedia, dużo łatwiej jest odnieść się do konkretnej linii kodu w Github czy Gitlab.
3. Twórz niezmienialną dokumentację, to będzie ją łatwiej utrzymywać - “że jak?!” zakrzykniesz? Już ponad 8 lat temu Michael Nygard opublikował na swoim blogu atrykuł o tytule “Documenting Architecture Decisions”, przedstawił w nim ideę tzw. ADRów, czyli Architecture Decision Record. Czyli zwięzły zapis naszych decyzji architektonicznych, powinien on zawierać:
4. tytuł - czego dotyczy zmiana,
5. kontekst - czyli opis “słowno muzyczny” skąd się wzięła taka potrzeba, jaką mamy aktualną sytuację projektową (zarówno biznesową jak i techniczną),
6. decyzja - czyli jakie rozwiązanie proponujemy na bazie powyższego opisu,
7. status - np. proponowany, zaakceptowany, odrzucony - tak tak, odrzucone pomysły też katalogujemy. Niosą one dużą wartość merytoryczną na temat naszego procesu myślowego. Możemy tez do odrzuconych propozycji wrócić gdy kontekst się zmieni i będziemy mogli przeanalizować go ponownie
8. konsekwencje - zarówno pozytywne i negatywne podjętej decyzji. Ważne aby nie malować trawy na zielono tylko pokazać też negatywne strony i ryzyka proponowanego przez nas rozwiązania

W moim aktualnym projekcie zwykle takie propozycje wysyłamy na forum ogólne (kanał na slacku), każdy może wejść i dorzucić swoje trzy grosze i dopisać komentarz w review. Wskazane jest, żeby również osoby z innych zespołów zabierały głos, bo często ta zmiana może ich dotyczyć bezpośrednio (np. zmiany w kontraktach wspólnych) lub też pośrednio (globalna zmiana architektoniczna, np. mechanizmu autoryzacji). Dodatkowym aspektem jest to, że często wewnątrz zespołu mamy podobne podejście i wpadamy w myślenie tunelowe. Rzut świeżym okiem często wychwytuje błędy, które samemu się ominęło. Przy podejmowaniu decyzji nie chodzi o poklepywanie się po pleckach, ale to by były dobre. No i najważniejsze, tak zaakceptowany dokument mergujemy i już nie zmieniamy - jeśli chcemy zmienić decyzję to dodajemy nowego ADRa. Dzięki czemu raz dodanej dokumentacji nie musimy aktualizować. Pięknie, nie?

4. Automatyzuj proces - Tak jak wspomniałem w poprzednich punktach, jest tyle fajnych i prostych narzędzi, które mogą nasz proces uczynić bezbolesnymi. Zachęcam do przejrzenia poprzednio podlinkowanego opisu jak my używamy Storytellera, czy też świetnego opisu Shaya Rojansky’ego jak robią to w Npgsql - bardzo podobnie zresztą jak my to robimy w Marten.

Czy to co mówię jest rewolucyjne? Nie bardzo, w większości projektów Open Source mniej lub bardziej jest to stosowane, rozwój Githuba oraz narzędzi bardzo ten proces ułatwił. Czy można to stosować również do dokumentacji biznesowej? A czemu nie, zwykle analitycy czy PO nie będą mieli wielkiego problemu z załapaniem Markdown.

Mam nadzieję, że pomogłem. Jak jest z tym u Ciebie w projektach? Czy macie podobne elementy używane? A może nie macie i uważasz, że to jest przerost formy nad treścią? Daj znać - chętnie poznam Twoją opinię!

Życzę spokojnego tygodnia i pozdrawiam serdecznie!

Oskar

p.s. Na koniec chciałbym jeszcze podzielić się dosyć osobistym wpisem, do którego zainspirował mnie SegFault - http://oskar-dudycz.pl/2019/11/30/zrodla-otwartosci/. Pierwszy wpis od 1,5 roku. Lecę może nieco Coelho, ale jest on ważny dla mnie emocjonalnie. Zachęcam do lektury. Daj znać co sądzisz.