logo

Struktura dokumentacji, która nie wymaga dużych nakładów pracy

Długość wpisu: 7 min

Jak to jest być skrybą, dobrze?

A, wie pan, moim zdaniem to nie ma tak, że dobrze, albo że niedobrze. Gdybym miał powiedzieć, co cenię w życiu najbardziej, powiedziałbym, że ludzi. Ludzi, którzy podali mi pomocną dłoń, kiedy sobie nie radziłem, kiedy byłem sam (…)

~Otis

Być skrybą to praktycznie to samo co pisać dokumentację.

To nie ma tak, że to jest fajne albo niefajne.

Jeśli najbardziej w życiu cenisz sobie ludzi, którzy podali Ci pomocną dłoń, to warto się odwdzięczyć i zostawić po sobie kawałek dobrze zrobionej dokumentacji.

Nie wiem jak Ty, ale ja bardzo często spotykam się ze stwierdzeniem, że np. pisanie dokumentacji to jedna z tych rzeczy, na które nie warto tracić czasu, bo zbyt szybko traci ważność.

Jednocześnie, zbyt wiele osób niepoprawnie zinterpretowało “Working software over comprehensive documentation” z Agile Manifesto, jako “nie trzeba pisać dokumentacji, wystarczy, że apka działa”.

Efekt jest taki, że w projektach, w których pracujemy, bardzo ciężko znaleźć przykłady dobrej dokumentacji. Nie wiem, czy kiedykolwiek się spotkałem z dobrą dokumentacją, a przeważnie po prostu jej nie ma.

Lata obserwacji nauczyły kilku rzeczy:

  • nie wiemy, czym tak naprawdę jest dokumentacja i po co ją piszemy, większość osób leci na yolo
  • nie wiemy, co to znaczy “wystarczająco dobra dokumentacja”
  • dobre przykłady mamy pod nosem, ale ich nie widzimy
  • uwielbiamy dobrą dokumentację, bo nam pomaga

Czym tak naprawdę powinna być dokumentacja?

Dokumentacja służy temu, żeby ułatwić pracę z kodem i ułatwić proces eksplorowania rozwiązania biznesowego. W tym kodu, który jest jedną ze składowych tego rozwiązania.

Powinna być prosta i na temat. Najlepiej nie za długa.

Simon Brown w świetnej książce “Software Architecture for Developers” przedstawił najlepszą metaforę dokumentacji, z jaką się spotkałem:

Traktuj dokumentację jako przewodnik.

Taki z mapami, historią, fajnymi miejscami do zobaczenia i w ogóle.

Sugeruje on, żeby w takim przewodniku znalazły się następujące elementy:

Mapy

Czyli wszelkiego rodzaju diagramy i obrazki. Ja również rozumiem przez to opis konkretnych funkcji z API.

Miejsca, które warto zobaczyć

Kluczowe moduły, elementy architektury (takie jak podejście do security, autentykacji) i fragmenty kodu, które mają największą wartość. Bez wchodzenia w szczegóły. Szczegóły znajdziesz na miejscu, czyli w naszym wypadku w kodzie. Albo w postaci zewnętrznego odnośnika.

Historia i kultura

Czyli dlaczego apka wygląda tak, jak wygląda. Kto podjął decyzje, dlaczego i co często najważniejsze, dlaczego apka nie wygląda tak, jak powinna.

Większość aplikacji jest nieidealna z konkretnych powodów. Brak czasu, skupienie się na MVP, jakiś pivot w trakcie implementacji spowodowany koronawirusem, który zostawił system w parszywym stanie, bo trzeba było szybko zmienić kierunek itp.

Ten element może być zaadresowany takimi rzeczami jak Decision Log.

Informacje praktyczne

Czyli wszelkiego rodzaje przykłady użycia, sposoby deployowania, ludzie, z którymi trzeba się kontaktować w razie pytań, wzorce i zasady stosowane w kodzie (np. “używamy Prettiera - tu jest link do configa”).

Czym jest “wystarczająco dobra dokumentacja”?

Wystarczająco dobra dokumentacja to taka, która nie pozwoli nam się zgubić.

Simple as that.

Za każdym razem, gdy masz jakieś pytanie, dokumentacja powinna pomóc Ci z odpowiedzią. Powinna wskazać punk startowy, w którym możesz szukać dalszych informacji.

Gdy miasz np. przewodnik po Górach Stołowych i zastanawiasz się nad listą ciekawych szlaków, to pewnie uzyskasz interesujące Cię informacje. A jeśli nie, to w tych przewodnikach zaznaczone są punkty informacyjne, do których możesz się udać, żeby te informacje uzyskać.

Czyni to z przewodnika taki hub, który pokazuje Ci kolejne kroki. I to jest wystarczająco dobre, bo pozwala ruszyć dalej. Nie pozwala się zgubić.

W taki sam sposób można traktować dokumentację.

Dobre przykłady mamy pod nosem

Gdy już wiadomo, jakie cechy ma dobra dokumentacja, to bardzo łatwo jest znaleźć przykłady w necie.

Ja zawsze odsyłam do Open Sourców, bo muszą poradzić sobie z wieloma wyzwaniami:

  • ciężko je koordynować, bo często prowadzi je grupa randomowych osób
  • każdy może kontrybuować, więc trzeba maksymalnie ułatwić te kontrybucje, żeby nie spędzać miliona godzin na zarządzaniu
  • projekt musi być dobrze opisany, bo inaczej nikt go nie będzie używał, albo zaleje Cię fala pytań i hejtu
  • musi być sprzedawalny, po wejściu na repo od razu musisz widzieć wartość

Często jako bardzo dobry przykład podaję repozytoria Kenta C. Doddsa, bo są bliskie perfekcji.

Są one atrakcyjne i dla osób, które z nich korzystają i dla osób, które chcą kontrybuować.

Przyjrzyjmy się, jak aplikuje elementy przewodnika w react-testing-library, gdzie przewodnik zaczyna się oczywiście w README.md. Czyli najprawdopodobniej najlepszym do tego miejscu.

Historia i kultura w react-testing-library

W skład historii i kultury wchodzi kontekst. Czyli dlaczego w ogóle robimy ten projekt i czym on jest. W kilku słowach. Uwielbiam RTL za to, że opisuje na samym początku jaki problem rozwiązuje:

rtl1.png

Pokazuje też zasady i decyzje, które zostały podjęte:

rtl2.png

Dostajemy krótki opis, dzięki któremu wiemy, czego możemy się spodziewać i dlaczego biblioteka działa w taki, a nie inny sposób.

Od razu widać elementy kulturowe, które wyróżniają ją od np. Enzyma, który pośrednio zachęca do testowania przez dobierania się do wnętrzności komponentu. Tutaj nie ma takiego czegoś.

Miejsca, które warto zobaczyć w react-testing-library

Miejsca, które warto zobaczyć, są tutaj głównie odsyłaczami do codesandboxów zamiast do konkretnych modułów rozwiązania.

Jednak jeśli chcesz testować hooki (jedno z moich pierwszych pytań, gdy zaglądałem do repo RTL), to od razu wiesz dokąd się udać.

rtl3.png

Miejsca, które warto zobaczyć, mocno zazębiają się w tym przypadku z informacjami praktycznymi.

Informacje praktyczne w react-testing-library

Tych jest tutaj najwięcej. Zaczyna się od warninga, który często można zobaczyć podczas odpalania testów:

rtl4.png

Tak jak pisałem:

Za każdym razem, gdy masz jakieś pytanie, dokumentacja powinna pomóc Ci z odpowiedzią.

Największy problem zaadresowany jest od razu <3.

Następnie mamy przykłady.

rtl5.png

Najpierw prosty przykład, a potem bardziej zaawansowany. Nie ma znaczenia, czy zaczynasz, czy potrzebujesz od razu czegoś więcej. Do wszystkiego masz dostęp “z roota”, czyli od razu w Readme, które też przekierowuje, gdzie trzeba.

Czyli do konkretnych map, o których za chwilę.

Na zakończenie w tej sekcji dostajemy jeszcze praktyczne info o tym, jak pracować z repozytorium, czyli jak ogarniać wszelkiego rodzaju issuesy i pytania (z linkami do Slacka i Discorda), a także kto pracował nad biblioteką.

Wiadomo kogo stalkować na Twitterze i gdzie uderzyć, jeśli chcemy szybko dostać odpowiedź :).

rtl6.png

rtl7.png

Mapy w react-testing-library

W przypadku RTL, mapy to po prostu poszczególne elementy API, które opisane są ogólnej dokumentacji testing-library (którego RLT jest częścią). Tutaj znowu przeplata się to mocno z informacjami praktycznymi.

Mamy odnośnik do osobnej strony (i przy okazji praktyczny link, jeśli te docsy chcemy edytować):

rtl8.png

I to nas przekierowuje tutaj:

rtl9.png

W przypadku komercyjnych projektów możemy tutaj mieć np. wygenerowany opis API RESTowego, jeśli uznamy, że jest nam to potrzebne. Jednak znacznie lepszym pomysłem wydaje się zestaw diagramów zapisanych w modelu C4.

Wygenerowane API jest raczej opcjonalne i nie trzeba go tu umieszczać, jeśli masz dobrze napisane testy albo fajnie opisany kod (jakiś JSDoc, czy cokolwiek).

Diagramy są już mniej opcjonalne, bo pokazują aspekty, których nie widać w kodzie. Są spojrzeniem na kod z lotu ptaka i ułatwiają zrozumienie.

Po co to wszystko

Tak jak wspominałem na początku, dokumentacja jest często zaniedbywana. Mało kto robi to dobrze i mało kto wie, że prowadzenie dokumentacji nie musi wiązać się z wielkim nakładem pracy.

Dzięki temu jest to jeden z obszarów, w których można się mocno wyróżnić. Bo my uwielbiamy dobrą dokumentację. Najprawdopodobniej nie korzystałbym z RTL, gdyby nie eleganckie Readme 🤷‍♂️.

Traktowanie dokumentacji jako przewodnika bardzo mocno zmniejsza nakład pracy, bo tak naprawdę musimy w niej trzymać tylko takie informacje, które wskażą dokąd się udać.

Pamiętam, że mój zespół bardzo pozytywnie zareagował, gdy pierwszy raz wspomniałem o prowadzeniu dokumentacji w ten sposób.

Przyjęło się to bardzo szybko i szybko otrzymaliśmy nieidealną, ale wystarczająco dobrą dokumentację. Zawierała w sobie wszystkie niezbędne informacje, które przyspieszały zrozumienie projektu i mogliśmy go oddać klientowi z czystym sercem oraz poczuciem zrobienia dobrej roboty.

Takie podejście do dokumentacji powoduje, że po dziś dzień osoby w moich projektach potrafią postawić sobie projekt i się w nim odnaleźć bez potrzeby zamienienia nawet jednego słowa z kimkolwiek. Ktoś kiedyś powiedział, że rzeczy powtarzalne należy automatyzować i to jest jedna z form tego przykazania.

Duma rozpierała mnie najbardziej, gdy jeden kolega podczas robienia prezentacji o Open Source wspomniał dokumentację projektu, nad którym razem pracowaliśmy i ocenił ją na solidne 10/12 punktów w jego skali. I’ll take it.

Warto też pamiętać, że jeśli robisz sobie przerwę od projektu, to tą osobą, która będzie potrzebować takiego przewodnika, będziesz właśnie Ty.

Także, bottom line - polecam stosować to podejście u siebie. Książka Simona Browna, z której zaczerpnąłem ten motyw, została mi polecona przez wielu świetnych programistów, do których zawsze wzdychałem, więc nie jest jakimś randomowym tworem randomowego szaleńca.

A gdy zaczniesz wprowadzać, to nie wszystko od razu, tylko jak zwykle, małymi kroczkami.

Link, o którym warto pamiętać: https://softwarearchitecturefordevelopers.com/

Koniecznie daj znać, jak wygląda sprawa z dokumentacją u Ciebie w projektach.

🖖

Wielu ludzi pyta mnie o to samo: ale jak ty to robisz, skąd czerpiesz tę radość? A ja odpowiadam, że to proste!

To umiłowanie życia. To właśnie ono sprawia, że dzisiaj na przykład buduję maszyny, a jutro – kto wie? (Napiszę dokumentację? przyp. autor)

~Otis

Podziel się:

Instagram, Twitter, YouTube, Facebook, LinkedIn