Szymon Warda: Cześć, słuchacie Patoarchitektów. Prowadzą Szymon Warda…

Łukasz Kałużny: I Łukasz Kałużny. Wszystkie linki do tego odcinka znajdziecie na Patoarchitekci.io/24. Poza miejscem, w którym słuchacie, być może na naszej stronie, możecie nas znaleźć również na Facebooku i Twitterze. Zapraszamy do obserwowania, lajkowania.

Szymon Warda: Linki.

Łukasz Kałużny: Linki. Ja mam wpis z blogu Cloudflare’a.

Szymon Warda: Bardzo dobry blog.

Łukasz Kałużny: Tak, zwykle bardzo fajne detale i aktualnie opisali swój proces wyboru nowej generacji serwerów, bo oni co jakiś czas budują sobie nową, wystandaryzowaną platformę dla wszystkich swoich rzeczy. I teraz robili porównanie dla nowej generacji Intel vs AMD, na tropie tego wszystkiego co się dzieje. I opisali dokładnie z czego będą korzystać, jak to testowali. I dla mnie to jest najciekawsze, że ze względu na swoją skalę oni testują, mają napisane swoje własne benchmarki pod te platformy serwerowe.

Szymon Warda: Mają dość charakterystyczne użycie, więc nie ma co się dziwić. No i oczywiście wybrali Ryzena.

Łukasz Kałużny: Tak, ale nie najmocniejszy procesor. To jest też ciekawostka, że wybrali 48 core’owe procki.

Szymon Warda: Tak. Czemu? Bo te najwyższe są mało wydajne energetycznie. A jak się ma farmę serwerów i dużo serwerów, to nagle te rachunki za prąd mają znaczenie.

Łukasz Kałużny: Tak, dokładnie. I druga sprawa, że potem jeszcze wykręcili z tego właśnie, walcząc z TDP wykręcili z AMD razem jeszcze 6% do ich zastosowań. Jak bardzo przy tej skali to rozszerzyli. Druga, to ciekawostka, że zaczynają wykorzystywać Secure Memory Encryption, które AMD daje. To też z takich bebechów patrzących. Więc polecam przejrzeć sobie ten wpis jak i inne, które są, bo są naprawdę mięsne technicznie z takimi low levelowymi rzeczami.

Szymon Warda: Z takich wpisów to jeszcze bardzo lubię blog Backblaze’a. To jest taka usługa, która robi backupy. Oni robią tam co kwartał testy dysków, wytrzymałości i tak dalej.

Łukasz Kałużny: Wrzucają zestawienie swoich dysków, ile im dysków padło, jakich, ile trwa wymiana.

Szymon Warda: Oni tam mają naprawdę dużo ich. Dobra, to teraz mój link. Ja ciekawy link, bardzo mocno w kontekście tego o czym będziemy dzisiaj mówili. Sokratyczne kontra euklidesowe podejście do dokumentacji. I teraz brzmi ciekawie. O co chodzi? Całkiem ciekawy wpis, który pokazuje jak można inaczej spojrzeć na dokumentację, na prowadzenie użytkownika przez dokumentację. I teraz o co chodzi? To euklidesowe podejście jest takie, że mówimy jakie mamy aksjomy, czyli jakie są fakty i pozwalamy użytkownikowi dojść co jest jak. Czyli najprostszy przykład opisujemy API.

Łukasz Kałużny: Po prostu robimy, dosłownie przerabiamy swagera na dokument.

Szymon Warda: Tak, najczęściej tak. Natomiast sokratyczne podejście jest trochę inne. Mianowicie okej, ono rozszerza właśnie euklidesowe, ale jeszcze prowadzimy użytkownika przez use case’y, przypadki użycia, dodajemy FAQ, dodajemy generalnie faktycznie ten biznes flow i jak nasze API może być wykorzystane. I naprawdę ciekawy wpis, który pojawił się swoją drogą na High Scalability. To pokazuje, że dokumentacja ważna jest przy skalowaniu szczególnie API, które wystawiamy, jeszcze oparty właśnie na dość ciekawym wpisie. Tak że polecam całość, mimo, że tak brzmi strasznie, tak, wydaje się takie naiwne, naprawdę dobry wpis i pokazuje generalnie jak można myśleć właśnie o dokumencie.

Łukasz Kałużny: Raczej dokumentowanie API jest niewdzięczną pracą.

Szymon Warda: Jest bardzo niewdzięczną, ale jest bardzo, bardzo ważną i bardzo mocno potem obniża ten cały narzut, który mamy na wyjaśnienie.

Łukasz Kałużny: Teraz zastanawiając się, który styl mi pasuje, powiem teraz bardzo głupio, to zależy, na to, który styl mi pasuje jako odbiorcy takiej dokumentacji.

Szymon Warda: Nie, to ja mam zdecydowanie sokratyczne podejście. Czyli że opis co jest, jak i flow, jak wyglądają - tak.

Łukasz Kałużny: Flowy tak przy większych usługach, przy prostych takie właśnie euklidesowe dla mnie jest wystarczające. Byle ktoś tylko dobrze napisał części ogólne wywarł, jak uwierzytelnianie, autoryzacje, albo jak mamy ID-ki budowane i URL-e do resource’ów.

Szymon Warda: Tak. To chyba już się wydało jaki będziemy mieli temat odcinka. Totalnie nie sexy. Dokumentacja.

Łukasz Kałużny: Najbardziej, szukam dokładnego, szukałem określenia, ale przychodzą mi same, które będzie trzeba wypikać, więc sobie podarujmy.

Szymon Warda: Tak. W ogóle skąd się to wzięło? Wzięło się z tego, że właściwie u nas ostatnio dość sporo działamy w kwestii dokumentacji i ile razy działaliśmy we wcześniejszych firmach, ile razy działałem, pomagałem, to zawsze to jest taki bardzo niewdzięczny temat, który spala dużo czasu, który jest konieczny. A nie oszukujmy się, rolą architekta jest pilnowanie, też, żeby ta dokumentacja była, żeby była dobra, bo dzięki temu zwiększamy przepływ wiedzy między zespołami w ramach całej firmy i zmniejszamy narzut na utrzymanie tak naprawdę.

Łukasz Kałużny: Jak patrzę w dokumentacji jest to, druga sprawa, dobra dokumentacja skraca onboardingi.

Szymon Warda: Bardzo, dokładnie.

Łukasz Kałużny: To jest problem, bo widzę na przykład niektóre, gdzie udokumentowana jest nawet głupia rzecz, jak prawidłowo zsetup’ować sobie środowisko developerskie czy w jakimś cloudzie, jak sobie zsetupować deployment dla siebie, środowiska. I nagle się okazuje w niektórych korporacjach, że przez pierwszy tydzień developer ma środowisko developerskie po pierwszym tygodniu, nie mówiąc już o commit’cie.

Szymon Warda: Tak i nie oszukujmy się, to jest z reguły temat, o którym mało kto mówi, a każdy na nim spalił setki godzin czasami. Więc przydałoby się podzielić się trochę wrażeniami.

Łukasz Kałużny: Dobra, to od czego, jeżeli tak inicjujesz i wychwalasz, to od czego zaczniemy?

Szymon Warda: Wychwalam, wychwalam. Parę punktów, które udało mi się spisać w kontekście tego, takie retro, co się działo. Pierwsze, to jest to, co wprowadziliśmy bardzo mocno u nas, to jest, jeżeli cokolwiek jest analizowane, to jest spisywane od razu. I teraz czemu?

Łukasz Kałużny: Teraz w ogóle mówisz o ADR-ze, że na początek zaczynając.

Szymon Warda: Niekoniecznie ADR, chodzi mi bardziej o to, że tak naprawdę, jeżeli cokolwiek jest analizowane, cokolwiek robimy, to spisujemy to. I teraz czemu? Podstawowy powód. Spisywanie powoduje, że myśli są układane lepiej i że w tym momencie mamy flow, jak to się zachowuje i tak dalej, łatwiej nam jest prezentować. Jeżeli tylko myślimy o tematach, to jest ok, wszystko wiem. Jak spisujemy, nagle jest ok, tu jest dziura, tu jest dziura, tu jest dziura. Ogarniamy temat i potem prezentując go do reszty zespołu jest czyściej przedstawiony, jest lepiej wydestylowany.

Łukasz Kałużny: To teraz jeszcze zadam Ci pytanie, bo to jest dla mnie zawsze problem. Mówisz analizujemy, ale co analizujesz? Bo to jest w kwestii dokumentacji projektowej, bieżącej?

Szymon Warda: Tak. I teraz lecimy właśnie generalnie, jak już mamy analizę, to teraz w co ją ubrać? Bo trzeba ubrać w jakieś tam template’y, gdzie możemy to ułożyć. I pierwszym takim to jest ADR.

Łukasz Kałużny: O którym mamy cały odcinek i zapraszamy wstecz.

Szymon Warda: Ale żeby rozwinąć skrót, bo za skróty jesteśmy trochę [niesłyszalne 00:06:59], architecture decision record.

Łukasz Kałużny: Tak, dokładnie, czyli dokumentowanie wszystkich zmian projektowych, zmian w architekturze, to jest ważne. Niewprowadzanie nowej klasy, tylko wprowadzenie, zmiana architektury.

Szymon Warda: Tak, dokładnie. Kolejnym elementem, który też zaczęliśmy mocno wprowadzać, to jest RCA - Root Cause Analysis. Czyli coś się, jakiś poważniejszy bug, coś się wywaliło, problemy wydajnościowe i tak dalej, spisywane to jest. I teraz czemu ważne? Zamieszczamy tam linki do zrzutów grafanowych, linki do Kibany i tak dalej. Łatwiej jest dużo wrócić do tego.

Łukasz Kałużny: Wszystko co miało, można określić, że RCA trzeba pisać, kiedy mieliśmy tak naprawdę, coś nam się wyłożyło na pysk dosłownie i albo ostro przekroczyliśmy SLA z jakichś powodów.

Szymon Warda: Albo generalnie zdarzyło się coś, czego do końca nie rozumiemy tak naprawdę. Bo to jest fajne, bo to jest takie miejsce do spisania, co się po kolei działo i spisania hipotez i potem do weryfikowania tych hipotez. No i ostatnim elementem oczywiście jest po prostu zwykły update albo insert do dokumentacji istniejącej, bo zmieniamy kawałek kodu, no to trzeba coś tam zaktualizować. I z reguły te trzy kategorie w zupełności wystarczają tak naprawdę.

Łukasz Kałużny: Tak. I teraz co popatrzysz? No i trzeba sobie odpowiedzieć pytanie, bo trochę dla mnie update do dokumentacji, czasami jeszcze robimy jakiś, nazwijmy to, w ramach projektów proof of concept. I gdzie on powinien Twoim zdaniem trafić w tym? Bo ja mam z tym mieszane uczucia. Czy powinien…

Szymon Warda: ADR, jeżeli to jest PoC. Czyli po PoC-u jest jakaś decyzja. Jaka jest decyzja? To jest ADR.

Łukasz Kałużny: Okej, można tak to przyjąć.

Szymon Warda: A!

Łukasz Kałużny: Mam Cię. Dobra, złapałeś mnie.

Szymon Warda: Jest! Tyle wygrać w życiu. Dobrze. Kolejny element to jest wszystko idzie do repo. Nie mamy Google Drive, nie mamy Dropbox’ów, nie mamy maili, błagam, bez maili i całej bandy innych rzeczy.

Łukasz Kałużny: Dobra, i teraz powiedziałaś jedną ważną rzecz - wszystko idzie do repo. Tu się zgodzę, bo sam… Fajnie jak dokumentacje mają razem z projektem. Te podejście katalog docs w roocie repo z open source’owych projektów, on się sprawdza, nie oszukujmy się.

Szymon Warda: Bardzo się sprawdza.

Łukasz Kałużny: Jeżeli jest to dobrze prowadzone. Tylko mam z tym problem, bo organizacje są często przeciwne temu. Jeżeli sobie popatrzysz, bo jest ukochane Wordy. Nie po to mamy wszystkie narzędzia tak zwane do kolaboracji, sharepointy Cconfluence’y.

Szymon Warda: To o tym powiemy sobie, bo faktycznie generalnie jest problem taki właśnie, że Wordy, PDF-y i tak dalej, z tym można sobie poradzić, jest Pandoc, który generuje załóżmy z markdown nam ładnie potem Worda. Tak, problem z confluence’ami jak najbardziej istnieje, ale z tym też sobie poradziliśmy w inny sposób.

Łukasz Kałużny: To jak?

Szymon Warda: Wystawiamy dokumentację w formie online. Teraz już wyprzedzając trochę, co się będzie działo, ale właśnie to jest ten kolejny punkt. Mianowicie, że dokumentacja jest wystawiana w formie online. I teraz czemu to jest ważne? A bo ludziom nietechnicznym łatwiej jest ją znaleźć. I zgodzę się. Mieliśmy rozmowy a propos tego, że Bitbuckety, GitHuby bardzo ładnie już renderują markdowna i dają duże możliwości. Ale jest jeszcze drugi element, który nam się bardzo sprawdził. Robimy mikro dokumentację. Wiecie co? Że jest ogólna strona dokumentacji, a poszczególne moduły systemu są w poddomenach dokumentacyjnych. Czyli mają osobne web site’y i można między nimi linkować płynnie. Więc osoba korzystająca z tej dokumentacji nie ma pojęcia, że to są różne kompletnie repa, które zasilają te strony jekyllowe.

Łukasz Kałużny: Wiesz co, tak tylko teraz to fajnie, że to powiedziałeś, a trochę widzę z tym problem. Patrzę, to jest moja perspektywa, problem z etapu, że zaraz ktoś powie: o Boże, ja potrzebuję na to znowu kilka dni.

Szymon Warda: Tak, takie ryzyko może być. Tylko że zrobiliśmy tak, że umówiliśmy się, że w markdownnie korzystamy z konkretnego engine’u i dzięki temu po prostu wystawiając tylko na poziomie ISA mamy prosty routing ustawiony i działa.

Łukasz Kałużny: Ok.

Szymon Warda: Nie jest idealne, ale działa. Tak że to wystawienie publiczne dokumentacji i że czemu to jest ważne? Bo sporo engine dokumentacji umożliwia zrobienie bardzo prostej opcji. Na web site dokumentacji masz przycisk, który automatycznie pobiera Ci PDF-a do tej całej dokumentacji. To jest fajne.

Łukasz Kałużny: Jest to fajne. Inaczej, to tak, ja się zgodzę wszystko, że do repo. Osobiście takie przeglądanie, uważam to, z perspektywy, w zależności jakich projektów, ale z perspektywy większości projektów, które są jednak prowadzone, nie oszukujmy się, wewnętrznie…

Szymon Warda: Że my akurat wystawiamy na zewnątrz naszą dokumentację.

Łukasz Kałużny: Tak, wystawia się na zewnątrz, ale że większość projektów, które są wewnętrzne, budowane na potrzeby wewnętrzne, czy to w software housie dla klienta, czy u klienta końcowego siedzi zespół deweloperski końcowego odbiorcy, to tak naprawdę w większości wypadków, jeżeli mamy jakiegoś Bitbucketa, GitHuba, GitLaba, Azure DevOpsa czy inne narzędzie do trzymania kodu, to tam ten silnik do wyświetlania zazwyczaj na potrzeby wewnętrzne zupełnie wystarczy i nie trzeba z tym kombinować.

Szymon Warda: Zgadzam się, mam tutaj, ale w kontekście tego, że np. będziemy też o tym mówili generalnie, o poziomach dokumentacji, do kogo są kierowane, na poziomie technicznym w zupełności się zgodzę. Jeżeli mówimy o dokumentacji na poziomie PO, takiej biznesowej i celach kwartalnych, takie w ogóle pokazywanie się, wewnętrzny marketing zespołu i tak…

Łukasz Kałużny: Przejdziemy dalej przy typach jak będziemy, bo widzę, że masz na to punkt. Dobra, to…

Szymon Warda: Jak do repo, to wszystko idzie przez PR-y.

Łukasz Kałużny: I tu się zgadzamy. Nie ma co w ogóle, ponieważ pull request daje nam możliwość komentowania tego.

Szymon Warda: Tak i to jest też bardzo ważne, to jest to, że mobilizuje do lepszego pisania i do weryfikacji, czy to jest prawda, do weryfikacji, czy coś się zmieniło. Nikt nie jest alfą i omegą i każdy ma prawo się pomylić, więc jak najbardziej. Generalnie to musi lecieć. Dobra.

Łukasz Kałużny: Dobrze.

Szymon Warda: Kolejny punkt.

Łukasz Kałużny: Artefakty. Wpisałeś sobie artefakty na listę. O co ci chodziło mój drogi?

Szymon Warda: Rzecz ważna, ponieważ załóżmy case jest taki, że często nasz system będzie wersjonowany. Budując system wypuszczają chociażby po to, żeby można było publikować rzeczy, to jest to, że razem z wersją publikujemy konkretną wersję aplikacji i…

Łukasz Kałużny: Dokumentacji.

Szymon Warda: Tak. Prosta sztuczka. Dzięki temu pobierając na przykład wersję X od razu mamy też te Docs’y, od razu mamy tego markdowna. I to się sprawdza bardzo.

Łukasz Kałużny: Wiesz co, ja to troszeczkę Ci wrócę do poprzedniego punktu. Wszystko idzie przez PR. Bo to jest trochę, to, co powiedziałeś o listach, jest trochę ze sobą powiązane z tym PR-em, a mianowicie, jeżeli jest to dokumentacja techniczna tak naprawdę od naszych bebechów, naszego systemu, to ona moim zdaniem powinna iść razem z pull requestem, z kodem.

Szymon Warda: Ależ oczywiście, że tak.

Łukasz Kałużny: Czyli jeżeli robimy pull request, to jest nasz kod i do tego korespondująca dokumentacja.

Szymon Warda: Zgadza się. Znaczy to ułatwia dużo fakt tego, że faktycznie doszliśmy do tego, żeby jednak katalog docs w repo był i możemy ewentualnie połączyć. Tak, bez dwóch zdań. Nie ma co tutaj większej dyskusji prowadzić.

Łukasz Kałużny: Dobra, to co teraz masz następnego na liście?

Szymon Warda: Kolejna rzecz, to wynika też z punktu, jak odbieram, to jest: nie będziesz miał plików poza tekstowymi.

Łukasz Kałużny: Dobra.

Szymon Warda: I tu jest gwiazdka, bo to jest uproszczenie jak zwykle, że plikami tymi źródłowymi są tekstowe, a potem możemy z nich generować co chcemy. Możemy generować PDF-y, możemy generować Wordy, możemy generować wszystko, SVG, PNG, cokolwiek. Ale jeżeli mówimy o PR-ach, to mówimy o pisaniu plików tekstowych. Czyli markdowny, ASCII, doc’i, o których będziemy pewnie jeszcze rozmawiali przez chwilę. To jest jedyna opcja, żeby iść tak naprawdę.

Łukasz Kałużny: Czy wiesz co i teraz tak, zaraz dojdziemy, bo będziemy mieli diagramy, bo to jest dla mnie takie odstępstwo.

Szymon Warda: Trochę tak.

Łukasz Kałużny: Tak. Nasza dokumentacja, tak, zgodzę się z tym, że powinno być to tam w tym docs, to jest głównie markdown, ale trafią się załączniki, więc też nie bądźmy purystami. Będzie PDX, PowerPoint, docs od biznesu.

Szymon Warda: Tak, ale…

Łukasz Kałużny: Sample, ale to jest coś co przyciągamy ze sobą jako taki artefakt, a nie jako rzecz, którą my wytwarzamy.

Szymon Warda: Dlatego właśnie mówiłem o plikach źródłowych generalnie, a to o czym mówiłeś, na nie się powołujemy jak najbardziej. Mam trochę mieszane uczucia, jeżeli chodzi o zipy, bo to jest takie średnie. To jak może być rozwiązane? Po prostu Git LFS, żeby po prostu nie rozdmuchiwało za bardzo repo. Ruszyłeś temat diagramów. I tu dla mnie osobiście wydarzyła się największa rewolucja jeżeli chodzi o, może się późno załapałem, o dokumentację, bo nie oszukujmy się, dobry diagram przepływu powie dużo więcej i dużo lepiej i lepiej ustrukturyzuje wiedzę niż opis tego w formie wordowej, czyli słowno-muzyczny. I o ile kiedyś był Mermaid JS, który był ok, ale po pierwsze, był brzydki jak sześć nieszczęść. Po drugie, to się tego nie dało wystylizować. Po trzecie, to działało w przeglądarce, więc tak nie do końca trzeba było cuda wianki robić w kontekście markdown. Ja odkryłem, nie wiem, może późno, dodatek do Visual Studio, do całego zestawu plików, PUML.

Łukasz Kałużny: Tak, tylko że on nie jest tak naprawdę Visual Studio też, powiedzmy sobie, tylko jest open sourceowy projekt, który już żyje i żyje.

Szymon Warda: Ale jest taki, że się mega fajnie integruje z Visual Studio Codem. To jest dość ważne. Plant UML i on umożliwia naprawdę robienie porządnych diagramów, stylizację. Tu mieliśmy dyskusję, że na starcie ona jest, te diagramy są brzydkie jak sześć nieszczęść, wyglądają jak Java z 90 lat.

Łukasz Kałużny: Bo to jest w Javie napisane w 2009, więc…

Szymon Warda: No to blisko byłem, ale naprawdę możliwości, jeżeli chodzi o wszystkie pozostałe diagramy, stylizacje, są ogromne. Jak to działa? Tu właśnie pojawia się to odstępstwo od tego, co mówiliśmy. To działa tak, że po prostu Visual Studio Code klikamy przyciskiem i po prostu przegenerowuje wszystkie diagramy do katalogu out.

Łukasz Kałużny: Czy to script czy cokolwiek, bo tak naprawdę jest to narzędzie. Czyli wejściowo mamy sobie plik z opisem naszego diagramu jakiegoś tam, jest coś a la JAML. Dobrze pamiętam, czy…

Szymon Warda: Taka dość dziwna składnia, do niczego niepodobna.

Łukasz Kałużny: Tak, do robienia grafów tak naprawdę troszeczkę można w niektórych miejscach porównać.

Szymon Warda: W sumie racja.

Łukasz Kałużny: W niektórych ten ASCII art, który wspominaliśmy przy GraphQL, raczej przy grafowych bazach.

Szymon Warda: Jest też jeden mega fajny feature. Jest podgląd na żywo.

Łukasz Kałużny: Tak, tylko, dobra, czyli z jednej strony masz plik wejściowy i możesz sobie potem z tego wygenerować diagram. Brzydki jak noc na dzień dobry i trzeba sobie to…

Szymon Warda: Ale można go stylizować.

Łukasz Kałużny: Wygląda gorzej niż Enterprise architekta. Dla mnie to jest już wyczyn.

Szymon Warda: Tak, zgodzę się, ta Java, takie szare kolory, przycięte. Ale to też wynika częściowo z tego, że sam PUML ma standaryzację pewnych kolorów, tak jak HTML, mamy pewne kolory nazwane i te kolory w większości są brzydkie jak sześć nieszczęść.

Łukasz Kałużny: Dobra, to jest tak, dla mnie jest to trochę wada, bo wprowadzamy kolejne gdzieś tam do stosu narzędzie. To jest wada i zaleta, jak kto popatrzy, do grafiki, bo znajdzie się dużo tradycjonalistów, którzy chcą przeciągnąć tą kreskę w Visio, Draw.io czy w innym narzędziu. I też…

Szymon Warda: O ile byłem fanem Draw.io, to jednak on generuje i tak musisz gdzieś ten plik trzymać, ściągasz na stronę i on….

Łukasz Kałużny: Możesz go sobie ściągnąć, zapisać, wiem. Workflow jest spaprany. Tak, jest upierdliwy, ale ludzie to stosują i też nie narzekają na to.

Szymon Warda: Może nie znają alternatyw.

Łukasz Kałużny: Tak.

Szymon Warda: Też stosowałem. Po Plancie do niczego innego już nie wrócę. Mermaida też porzuciłem kompletnie.

Łukasz Kałużny: Dobra, to jest Twoja. Ja tak patrzę, dla mnie może takie odstępstwo, czyli te diagramy. Najważniejsze, że nieważne w czym rysujesz, tylko ten plik źródłowy niech znajdzie się w tym repo, z czego generujesz. To bardziej nawet niż… Wiem, że fajnie właśnie ten Plant UML, przez Ciebie też będę chciał go sobie zobaczyć. Może kogoś oświecę nim albo wskażę go na niego, zobaczymy jaki będzie werdykt po jakimś czasie używania. Ale tak naprawdę jeżeli diagramy, to jest bardzo ważne, to gdzieś sobie zapisałeś w notatkach nawet widzę, że wyjaśnia więcej niż tysiąc słów - dobry diagram.

Szymon Warda: Tak.

Łukasz Kałużny: To właśnie zapisz ten plik źródłowy razem z nim. Wygeneruj go tak, żeby się pojawił na stronie. I jeżeli mówimy o obrazkach, to przydałoby się powiedzieć, jak je rysować wstępnie.

Szymon Warda: Wyjaśnij pytanie.

Łukasz Kałużny: Jak dobrze narysować diagram? Jak złapać dobrze kontekst w diagramie?

Szymon Warda: O to Ci chodzi, dobrze.

Łukasz Kałużny: O to chodzi.

Szymon Warda: Dochodzimy do tego, co jest bardzo potrzebne w dokumentacji i co często, szczególnie osoby techniczne, gubią kompletnie, ten clue. To co mówimy w ogóle w IT, że kontekst jest królem, do dokumentacji też się odnosi. Pamiętajmy, że jest coś takiego jak C4. Całe podejście właśnie do dokumentacji architektury systemu…

Łukasz Kałużny: Do wizualizacji.

Szymon Warda: Powiedzialbym inaczej, do spojrzenia co usunąć, co nie usunąć, co powinno być na obrazku tak naprawdę.

Łukasz Kałużny: Tak, bo oni sami nawet się nazywają, że to jest model dla wizualizacji software’owej architektury.

Szymon Warda: Tak, bo co się często widzi w dokumentacji, to jest to, że otwieramy dokument i na starcie mamy zejście na bardzo niskie szczegóły. A to jest to, co mówi C4, pierwszym kluczem jest kontekst w ogóle, co to robi, do czego jest, bo możliwe, że nasz system…

Łukasz Kałużny: Wiesz co, to może rozwińmy C4, bo to się by przydało. Ja też w którymś odcinku solo poruszałem C4, ale to rozwińmy. Czyli jest pierwszy poziom, to jest kontekst, czyli to jest taki high levelowy przegląd. To jest high levelowy, czyli nasz system, nasze rozwiązanie w porównaniu z resztą ekosystemu, z którą się integruje.

Szymon Warda: Tak, dokładnie, co robi, po co jest, jak żyje i taki ogólny opis, żebyśmy widzieli w ogóle z jakim zwierzęciem mamy do czynienia.

Łukasz Kałużny: Kiedy mamy, rzucając taki ich przykład, bo mi się on podoba, to jest dla systemu bankowego, czyli my piszemy system transakcyjny, jego dokumentujemy, no i gdzieś z boku mamy na przykład system e-mailowy, z którym do wysyłania powiadomień i innych rzeczy, a z drugiej strony mamy cały corebankimg na jakimś mainframe’ie. Więc umieszczamy nasz system w tym kontekście tego ekosystemu, z którym pracuje.

Szymon Warda: Tak, idąc poziom niżej, schodzimy na poziom kontenerów, czyli generalnie jak się komunikujemy i takie duże bloczki.

Łukasz Kałużny: Grube moduły w naszej aplikacji.

Szymon Warda: Tak.

Łukasz Kałużny: Grube, to rzućmy jakimś przykładem. Grubym modułem będzie baza danych, będą jakieś mikroserwisy, każdy z osobna, będzie jakiś frontend, SPA, mobilna aplikacja, API Application. Czyli jesteśmy na poziomie pojedynczych, dużych modułów, które możemy wyszczególnić.

Szymon Warda: Tak, potem schodzimy sobie na kontenery…

Łukasz Kałużny: Komponenty.

Szymon Warda: Komponenty, czyli generalnie takie można powiedzieć moduły naszych klas. Ja to często porównuję do folderów w solucji.

Łukasz Kałużny: Tak, do niektórych folderów jak mamy jakąś http API albo coś, to mogą być w .Necie, to są kontrolery, czy w zależności jak tam w innym języku się to zwie, jakie mamy podejście. Czyli grube komponenty już w naszym module. Czyli grube części naszego mikroserwisu na przykład.

Szymon Warda: A na końcu na końcu mamy zwykły kod, do którego ja z reguły nie schodzę, bo jest kolejny element. Jeśli chodzi o dokumentację, to pamiętajmy, że dokumentacja jest kosztem i utrzymanie jej jest drogie. A najgorszą dokumentacją jest nieaktualna dokumentacja. Ostatni punkt, 10. Pamiętajmy, że są 2 typy dokumentacji, tak samo jak są dwa główne typy naszych odbiorców.

Łukasz Kałużny: Raczej może typy dokumentacji. Typy odbiorców chyba jest lepszym określeniem.

Szymon Warda: Jedno implikuje drugie, ale pierwsze to jest techniczne, które pamiętamy z reguły, a drugie to jest biznesowe, a nie kontekstu, co ten system w ogóle robi, jak robi, jakie są procesy biznesowe, jakie też test case’y realizuje, bo to też jest bardzo, bardzo ważne. Bo to, żeby nowy developer mógł się ogarnąć generalnie, że zrobił zmianę w jakimś tam workflow, to który test odpalić, jak to się mapuje. I pamiętajmy bardzo mocno, że ten wstęp biznesowy, który często powinien dobry PO zrobić, to w tym momencie też powinno być elementem dokumentacji. I to jest bardzo, bardzo ważne. No i na samym starcie przede wszystkim mamy taki C-level, skrót całego systemu, czyli pół strony opisu, który mówi…

Łukasz Kałużny: Kontekst i co to w ogóle robi?

Szymon Warda: Tak, dokładnie.

Łukasz Kałużny: Wiesz co jeszcze? Tak. Co do biznesowej. Bo jest problem, bo troszeczkę powiedzieliśmy o analizie. Ja Cię też łapałem za to. Druga rzecz, że jest taka często nadal klasyczna analiza biznesowa, gdzie Enterprise Architect i inne rzeczy się sprawdzają, często lepiej niż podejście, które techniczne tutaj opisaliśmy.

Szymon Warda: Tak, zgadza się, przy dokumentacji na skalę całej korporacji jak najbardziej, tak, to musi być.

Łukasz Kałużny: Czyb na skalę biznesową, kiedy analizujesz, kiedy taki rasowy analityk biznesowy wpada, dokumentuje proces i inne rzeczy, zbiera wymagania.

Szymon Warda: Mam z tym mieszane uczucia. Też tak kiedyś uważałem, ale po ostatnich doświadczeniach z naszym wspaniałym PO stwierdzam, że nauczenie kogoś i Gita i wszystkich diagramów i tak dalej, naprawdę…

Łukasz Kałużny: Wiesz co, może inaczej, z drugiej strony. Pracowałem z ludźmi, którzy umieli w na przykład Enterprise Architecta w narzędzia do zbierania, określania wymagań i na przykład stamtąd przegenerowanie ładnego Worda do biznesu, to było kliknięcie. Sam zresztą z paroma takimi osobami pracowałeś, które potrafiły spisać wymagania i z tych wymiocin, które znajdowały się w Enterprise Architect’cie, nagle generowała się dokumentacja, która była do użytku potem, do akceptacji biznesu czy potem przekazania już jako wejście do developmentu, wymagań.

Szymon Warda: Zostaje nam jeszcze jedna dość ważna dyskusja, która się obecnie zaczęła toczyć, markdown kontra AsciiDoc.

Łukasz Kałużny: No dobra, ja mam, bardzo prosto powiem, markdown jest, aktualnie można powiedzieć, że stał się takim quasi standardem. Przyzwyczailiśmy się do niego, stosowania.

Szymon Warda: Dobrze, że użyłeś quasi, bo markdown w sumie nie jest, ma tyle dziur, jeżeli chodzi o standaryzację.

Łukasz Kałużny: Wiem, dlatego użyłem słowa quasi, bo mamy ileś jego odmian, tudzież smaków. Jak to ten, przyprawiony GitHubem, przyprawiony czym innym.

Szymon Warda: I to jest jego największy problem. Ale jaka jest różnica podstawowa? To jest, że AsciiDoc jest dość taką konkretną specyfikacją, ma dużo więcej feature’ów. Ma takie opcje jak ustawienie szerokości. Wszędzie tam, gdzie w markdownie robimy fallback na HTML-a wstrzykiwanego, co nie jest idealne, nazwijmy to, to Ascii ma to ładnie bardzo ogarnięte, ma dużo więcej feature’ów. Problemem jego jest to, że faktycznie domyślnie nie jest renderowany i mało co go wspiera na wejściu. Czyli jak mamy plik readme w AsciiDocu, to jest już trochę gorzej.

Łukasz Kałużny: Nie, dla mnie, to jest popularność tego. Jeżeli pójdę na salę, powiedzmy pójdziemy sobie na losową konferencję na temat developmentu i zapytajmy się, ile osób wie, co to jest markdown, a ile osób słyszało o AsciiDoc. Domyślam się wyniku.

Szymon Warda: Tak, jedno ale, w systemach do generowania dokumentacji AsciiDoc zyskuje dość sporo użycia tak naprawdę, coraz częściej się go zauważa.

Łukasz Kałużny: Wiesz co i teraz rozróżnijmy. Ja bym rozróżnił jedną ważną rzecz, bo powiedzieliśmy sobie o naszej wewnętrznej dokumentacji. Jest sobie pozycja tak zwanego technicznego pisarza, jak to się śmieję, po polsku, w różnych organizacjach, który pisze techniczną dokumentację dla klienta zewnętrznego. I tak naprawdę taka osoba musi być extechniczna, musiała rozumieć co pisała. I tam są troszkę inne… Korzysta się z zupełnie innych formatów. Taki AsciiDoc, jest parę jeszcze innych rozwiązań do generowania, spisywania, generowania publicznej dokumentacji. Tylko to jest zupełnie inna kwestia. Ja rzucę ciekawostkę na przykład z Microsoftu. Cały Azure na przykład, teraz .Net też na to przechodzi, jest pisany w repach GitHub’owych, w Microsoft Flavored Markdown.

Szymon Warda: Tak i z dużych plusów, jak się na te repa wejdzie, to strona Microsoftu nie przełączy na język polski.

Łukasz Kałużny: Tak, to jest duży plus. Ale nie, chodzi o to, że też dali cały tooling. Tam jest plugin chyba do Visual Studio Code, żeby ładnie renderować sobie lokalnie tą dokumentację. I oni mają taki cały system, który Wy sobie zrobiliście teraz, opisałeś o nim przy swoim projekcie, do mikrodokumentacji.

Szymon Warda: Można też zgłaszać PR-y i tak dalej i tak dalej. Wiem, bo faktycznie…

Łukasz Kałużny: To jest też takie właśnie z jednej strony mamy takie standardy jak AskiDoc czy inne przeznaczone takie stricte do pisania. Moglibyśmy w LabTechu również pisać, jeżeli na to od tej strony, jeżeli popatrzysz na generowanie, a z drugiej strony szybkość pisania. Ja bym dorzucił jeszcze jedną rzecz, styl pisania w środku takiej dokumentacji, bo ludzie na siłę piszą okrągłe zdania.

Szymon Warda: Punktowanie jest potęgą. Pisanie długich, złożonych zdań jest przerażające i powoduje, że będzie nieczytelne.

Łukasz Kałużny: Raczej keep it simple stupid. Tak samo co do dokumentacji.

Szymon Warda: Tak i ja w kontekście dokumentacji, szczególnie angielskiej, polecam Grammarly, bo ono właśnie bardzo mocno punktuje zdania złożone i punktuje za nieczytelność tych zdań.

Łukasz Kałużny: W Polsce jest jeszcze jasnopis, też jest taka usługa do polskiego, Jasnopis, więc…

Szymon Warda: Może być, dla mnie jeszcze dość ważna decyzja, dyskusja właściwie, która się pojawiła, to było kto pisze dokumentację? Bo często jest tak i to z tym się spotykam, że dokumentację pisze jedna osoba. Często jest to lider albo wyznaczona, albo jakiś tam PO.

Łukasz Kałużny: Ktoś, kto wygrał pisanie dokumentacji.

Szymon Warda: Wygrał, przegrał, różnie może być. A my zrobiliśmy podejście takie, że jednak pisze cały zespół i to się super sprawdza.

Łukasz Kałużny: To jest tak jak z ADR-ami, Ty podniosłeś, Ty tworzysz ADR-a.

Szymon Warda: Tak, my nawet do tego stopnia, że jak mamy jakieś dokumenty, to rozbijamy go na działy i w tym momencie po prostu to są taski do wzięcia przez każdego.

Łukasz Kałużny: Raczej to jest wiesz, to tak jak powiedzieliśmy o dokumentacji samego potem tego, co mamy w bebechach. Trochę powiedzieliśmy, że dokumentacja powinna iść z pull requestem, więc jest się jednoznacznie wskazany wtedy, można powiedzieć kto pisał dany kawałek.

Szymon Warda: Jasne. Dobra, podsumowujmy to.

Łukasz Kałużny: Wiesz co, może jeszcze problemy? W szczególności od strony repo. Bo jest jeden problem, o którym jakoś przemilczeliśmy, w szczególności Ty.

Szymon Warda: Tak, ja przemilczałem go, bo jest problem taki, że jeżeli wystawiamy dokumentację client facing publiczną, to niestety problem z wersjonowaniem jest taki, że ciężko i przynajmniej nie udało mi się znaleźć narzędzi, tego chociażby co robi Elastic, że mamy przełącznik między różnymi rodzajami wersji. Jak ktoś zna, niech podeśle, chętnie skorzystamy.

Łukasz Kałużny: Dla danego release’u.

Szymon Warda: Tak. Jedyna opcja na razie jaką mam wykombinowaną, to jest po prostu zbieranie tego z artefaktów. Ale nie, automatyzacja tego jest co najmniej słaba niestety.

Łukasz Kałużny: Dobra, to co podsumowujemy?

Szymon Warda: Tak, mój pierwszy to jest Plant UML. Zachęcam do diagramów, bo zrewolucjonizował moje podejście do robienia diagramów.

Łukasz Kałużny: Diagram as code, to tak. Ja tak…

Szymon Warda: Tak.

Łukasz Kałużny: Cierpię, chciałbym żeby coś było wbudowanego w GitHuba i Bitbucketa, byłbym wtedy szczęśliwym człowiekiem.

Szymon Warda: Tam były jakieś podejścia, ale nie.

Łukasz Kałużny: Żeby się wystandaryzowało coś w ramach repo do rysowania, to byłoby super. Ale podsumowujmy. Tak, diagram as code. Tak, można sprawdzić co Szymon mówi z Plant UML-em. Ja się jeszcze pod tym nie podpisuję. To nie jest moja twarda rekomendacja. Do diagramów tak, róbcie diagramy.

Szymon Warda: Tak. Wszystko w repo, to już chyba nie trzeba przekonywać. I naprawdę wszystko, wszystko leci łącznie z, u nas łącznie z odpowiedziami do klienta.

Łukasz Kałużny: Następnie markdown nie gryzie powiedzmy sobie, w ogóle pisanie nie powinno gryźć.

Szymon Warda: Nie powinno, zdecydowanie.

Łukasz Kałużny: Podsumowując, jeżeli masz problem z pisaniem, to są tylko punkty. Tak naprawdę pisać punktami, bardzo prostymi zdaniami, raz, dwa, trzy albo kropeczkami, w zależności jak tam idzie proces. Na większe zdania się wysilamy, kiedy faktycznie musimy coś bardziej opisać, a być może diagram będzie prostszy.

Szymon Warda: Tak. Co więcej, jak puszczamy to przez PR-y, to się nauczymy. To, co mówił Stephen King: pisanie jest mięśniem, który trzeba trenować. Dobra, tyle, kończymy.

Łukasz Kałużny: Kończymy. Na razie.