#24 Dokumentacja...

2020, Mar 13

Jeden z najnudniejszych, najmniej seksownych, najczęściej odsuwanych w czasie tematów w projektach? Dokumentacja! W tym odcinku rozmawiamy właśnie o niej…

Ciekawe linki i inne znaleziska z tego odcinka:

Transkrypcja

Szymon: Cześć! Słuchacie Pato Architektów. Prowadzą Szymon Warda

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

S: Linki.

Ł: Ja mam wpis z blogu Cloud Flare’a:

S: Bardzo dobry blog.

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

S: Mają dość charakterystyczne użycie, więc nie ma co się dziwić. No i oczywiście wybrali Ryzen’a.

Ł: Tak, ale nie najmocniejszy procesor. To też jest ciekawostka, że wybrali 48 corowe procki.

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

Ł: Dokładnie. I druga sprawa, że potem jeszcze wykręcili z tego właśnie walcząc z DPD, 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. Polecam przejrzeć ten wpis jak i inne, które tam sa, bo są naprawdę mięsne technicznie, z takimi low-levelowymi rzeczami.

S: Z takich wpisów to jeszcze bardzo lubię blog Bart Blaze’a. To jest taka usługa, która robi backup’y. Tam co kwartał robi test dysku, wytrzymałości.

Ł: Zrzucają zestawienie swoich dysków, ile im dysków padło, jak, ile trwają…

S: Oni mają ich bardzo wiele. Dobra, to [teraz mój link](http://highscalability.com/blog/2020/2/24/socratic-vs-euclidean-forms-of-api-documentation.html To jest ciekawy link w kontekście tego, o czym dzisiaj będziemy mówili. Sokratyczne kontra Euklidesowe podejście do dokumentacji. Ha! 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ść do co jest jak. Najprostszy przykład: opisujemy api.

Ł: Po prostu dosłownie przerabiamy swagger’a na dokument.

S: Tak, najczęściej tak. Natomiast to Sokratyczne podejście jest trochę inne. Mianowicie ono rozszerza podejście Euklidesowe, ale jeszcze prowadzimy użytkownika przez use case’y, przypadki użycia, dodajemy FAQ, dodajemy business flow, jak nasze api może być wykorzystane. Naprawdę ciekawy pis, który pojawił się swoją droga na High Scalability. To pokazuje, że dokumentacja jest ważna, przy skalowaniu szczególnie api, kiedy je wystawiamy. Jeszcze oparty na dość ciekawym wpisie. Także polecam całość, mimo że…

Ł: Brzmi strasznie.

S: Tak. Wydaje się takie naiwne. Naprawdę dobry wpis i pokazuje generalnie, jak można myśleć o dokumencie.

Ł: Dokumentowanie api jest raczej niewdzięczną pracą.

S: Ale jest bardzo ważną i bardzo mocno obniża narzut, który będziemy mieli do wyjaśnienia.

Ł: 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.

S: Ja mam zdecydowanie Sokratyczne podejście, że opis co jest jak oraz flow jak wyglądają.

Ł: Flowy tak, przy większych usługach. Przy prostych takie podejście Euklidesowe jest dla mnie wystarczające. Byle ktoś dobrze napisał części ogólne, tj. uwierzytelnianie, autoryzacje. Albo jak mamy id wbudowane i urle do resource’ów.

S: Zgadza się. To już się chyba wydało, jaki będziemy mieli temat odcinka. Totalnie nie sexy – dokumentacja.

Ł: Najbardziej…szukałem określenia, ale przychodzą mi same, które trzeba będzie wypikać, więc sobie podarujmy.

S: Tak. Skąd to się wzięło? U nas ostatnio dość sporo działamy w kwesti dokumentacji. Ile razy wcześniej pomagałem, to był bardzo niewdzięczny temat, który spala dużo czasu i jest konieczny. Nie oszukujmy się – rolą architekta jest pilnowanie, żeby ta dokumentacja była i żeby była dobra. Dzięki temu zwiększamy przepływ wiedzy między zespołami w ramach całej firmy i zmniejszamy narzut na utrzymanie tak naprawdę.

Ł: Wiesz co? Tak jak patrzę to dobra dokumentacja skraca nam onboardingi.

S: Bardzo!

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

S: Nie oszukujmy się. To jest temat, o którym mało kto mówi, a każdy na nim spalił setki godzin czasami. Więc przydałoby się podzielić wrażeniami.

Ł: Dobra. Skoro tak inicjujesz i wychwalasz, to od czego zaczniemy?

S: 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, czyli jeżeli cokolwiek jest analizowane, to od razu jest spisywane.

Ł: Teraz w ogóle mówisz o ADR. Tak zaczynając.

S: Niekoniecznie od ADR-u. Chodzi mi bardziej o to, że tak naprawdę, że cokolwiek jest analizowane, cokolwiek robimy, to spisujemy to. Teraz czemu? Podstawowy powód: spisywanie powoduje, że myśli są układane lepiej i że w tym momencie mamy flow, jak się to zachowuje, itd. Łatwiej nam jest prezentować. Jeżeli tylko myślimy o temacie to myślimy: „jest ok, wszystko wiem”. Jak spisujemy, to widzimy, że „tu jest dziura”, ogarniamy temat. Potem prezentując go reszcie zespołu jest czyściej przedstawiony, jest lepiej wydestylowany.

Ł: To teraz 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.

S: Tak. I teraz, jak już mamy analizę, to teraz w co ją ubrać? Czy ubrać w jakiś template, w którym możemy go ułożyć. I pierwszym takim jest ADR.

Ł: O którym mamy cały odcinek i zapraszamy wstecz.

S: Dokładnie. Rozwińmy skrót: Architecture Decision Record.

Ł: Dokładnie. Czyli dokumentowanie wszystkich zmian projektowych, zmian w architekturze. To jest ważne. Niewprowadzenie nowej klasy, tylko wprowadzenie zmiany architektury.

S: Dokładnie. Kolejnym elementem, który też zaczęliśmy mocno wprowadzać to jest RCA. Root Cause Analysis. Czyli jest jakiś poważniejszy bug, coś się wywaliło, mamy problemy wydajnościowe. Spisywane to jest, zamieszczamy tam linki do rzutów Grafanowych, do Kibany. Łatwiej jest wrócić wtedy do tego tematu.

Ł: RCA trzeba pisać, kiedy coś się nam wyłożyło na pysk, dosłownie. Albo ostro przekroczyliśmy SLA z jakichś powodów.

S: Albo generalnie zdarzyło się coś, czego do końca nie rozumiemy. To jest miejsce do spisywania co się po kolei działo, spisania hipotez i potem ich weryfikowania. Ostatnim elementem jest oczywiście zwykły update albo insert do dokumentacji. Tej istniejącej, bo zmieniamy kawałek kodu, więc trzeba coś tam aktualizować. I z reguły te trzy kategorie w zupełności wystarczają.

Ł: Teraz odpowiedzmy sobie na pytanie, bo update do dokumentacji czasami robimy w ramach projektów typu proof of concept. Gdzie on powinien Twoim zdaniem trafić? Ja mam z tym mieszane uczucia.

S: W ADR, jeżeli jest to POC. POc to jest jakaś decyzja. Jak jest decyzja to jest ADR.

Ł: Ok. Można tak to przyjąć.

S: Ha!

Ł: Dobra, złapałeś mnie ;)

S: Tyle wygrać w życiu  Dobrze. Kolejny element to: wszystko idzie do Repo. Nie mamy Google Drive, nie mamy Dropbox, nie mamy maili. Błagam! I całej bandy innych rzeczy.

Ł: Teraz powiedziałeś jedną ważną rzecz. Wszystko idzie do Repo: tu się zgodzę, bo fajnie jak mam dokumentację razem z projektem. To podejście: katalog, docs, wróć repo, w open sourceowych projekttach on się sprawdza, nie oszukujmy się.

S: Bardzo.

Ł: Jeżeli jest to dobrze prowadzone. Tylko mam z tym problem, bo organizacje są często przeciwne temu. Jeżeli sobie popatrzysz to są ukochane Wordy, nie po to mamy te wszystkie narzędzia do kolaboracji, Sharepointy, Confluence’y.

S: O tym powiemy sobie, bo faktycznie generalnie jest problem taki, że Wordy, PDF’y itd. Z tym można sobie poradzić. Jest Pandoc, który generuje nam Worda z markdown’a. Problem z Confluence’ami jak najbardziej istnieje, ale z tym też sobie poradziliśmy w inny sposób.

Ł: Jak?

S: Wystawiamy dokumentację w formie online. Teraz już wyprzedzając trochę to, co się będzie działo, ale to jest właśnie ten kolejny punkt: dokumentacja w formie online. Czemu to jest takie ważne? Ludziom nietechnicznym łatwiej jest ją znaleźć. Mieliśmy rozmowę, że Bitbucket’y i Githuby bardzo ładnie shareuja breakdown’a i dają duże możliwości. Jest jeszcze drugi element, który nam się bardzo sprawdził. Robimy mikrodokumentację. Jest ogólna strona dokumentacji, a poszczególne moduły systemu są w poddomenach dokumentacyjnych. Czyli mają osobne website’y, i można między nimi płynnie linkować, więc osoba korzystająca z tej dokumentacji nie ma pojęcia, że to są różne kompletnie repa, które zasilają te strony Jeckyllowe.

Ł: Wiesz co, tak, tylko, że fajnie, że o tym powiedziałeś, bo widzę, że jest z tym problem. To jest moja perspektywa: problem setupu, że zaraz ktoś powie: „O Boże! Ja potrzebuję na to znowu kilku dni”.

S: Tak, takie ryzyko może być. Załóżmy, że umówiliśmy się, że w markdownie korzystamy z konkretnego engine’u, i dzięki temu wystawiając na poziomie IS’a mamy prosty rooting ustawiony i działa.

Ł: Ok.

S: Nie jest idealny, ale działa. Także to wystawienie publiczne dokumentacji i że czemu to jest ważne, bo sporo engine’ów dokumentacji umożliwia skorzystanie z bardzo prostej opcji. Na website dokumentacji masz przycisk, który automatycznie pobiera PDF’a dla tej całej dokumentacji. To jest fajne.

Ł: Tak, jest fajne. Ja się zgodzę z zasadą: wszystko do repo. Osobiście takie przeglądanie uważam za dobre w zależności od projektów, ale z perspektywy większości projektów, które są prowadzone, nie oszukujmy się, wewnętrznie.

S: My akurat wystawiamy na zewnątrz dokumentację.

Ł: Tak, wy tak, ale że większość projektów są wewnętrzne, nabudowane na potrzeby różnych rzeczy, czy to w software house dla klienta czy u końcowego klienta siedzi zespół deweloperski i końcowego odbiorcy. Tak naprawdę w większości wypadków, jeżeli mamy jakiegoś Bitbucket’a, Github’a, Gitlab’a, Azure Devops’a, czy inne narzędzie do trzymania kodu, to tamten silnik do wyświetlania zazwyczaj na potrzeby wewnętrzne zupełnie wystarczy. I nie trzeba z tym kombinować.

S: Zgadzam się. Mam tutaj ALE w kontekście tego, że na przykład będziemy mówili generalnie o poziomach dokumentacji. Na poziomie technicznym się w zupełności zgodzę. Jeżeli mówimy o dokumentacji na poziomie PO takiej biznesowej i celach kwartalnych, wewnętrzny marketing zespołu, to tak różnie.

Ł: To przejdziemy z tym dalej. Widzę, że masz do tego przygotowany punkt.

S: Tak. Jak biorę Repo, to wszystko idzie przez PR’y.

Ł: Tu się zgadzamy. Nie ma co w ogóle, ponieważ pull request daje nam możliwość komentowania tego.

S: Tak, to jest bardzo ważne i mobilizuje do lepszego pisania. I do weryfikacji czy to jest prawda, do weryfikacji czy coś się zmieniło, nikt nie jest alfą i omegą. Każdy ma prawo się pomylić, więc to musi lecieć. Kolejny punkt?

Ł: Artefakty. Wpisałeś je sobie na listę. O co Ci chodziło, mój drogi? ;)

S: Rzecz ważna, ponieważ załóżmy case jest taki, że często nasz system będzie wersjowany, budując nasz system wypuszczamy po to, żeby można było publikować rzeczy, razem z wersją publikujemy konkretną wersję aplikacji i…

Ł: I dokumentacji.

S: Tak. Prosta sztuczka: dzięki temu pobierając na przykład wersję X od razu mamy też te docsy i markdown’a. I to się sprawdza bardzo.

Ł: Wiesz co, ja wrócę troszkę do poprzedniego punktu i powiem, że wszystko idzie przez PR. To co powiedziałeś o release’ach jest ze sobą trochę powiązane. Z tym PR. Mianowicie, jeżeli jest to dokumentacja techniczna, od naszych bebechów, systemu, moim zdaniem powinna iść razem z pull requestem z kodem.

S: Oczywiście.

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

S: Zgadza się. Doszliśmy do tego, żeby katalog docs w repo był i możemy to ewentualnie połączyć. Bez dwóch zdań, nie ma co tu większej dyskusji prowadzić.

Ł: Dobra, to co teraz masz następnego na liście?

S: Kolejna rzecz: nie będziesz miał plików poza tekstowymi.

Ł: Dobra.

S: I tu jest gwiazdka, bo to jest uproszczenie jak zwykle. Plikami źródłowymi są tekstowe, a potem możemy z nich generować co chcemy: PDF’y, Word’y, wszystko, .svg, .png, cokolwiek. Ale jeżeli mówimy o PR’ach, to mówimy o pisaniu plików tekstowych. Czyli markdowny, AsciiDoc’i, będziemy o nich również rozmawiali przez chwilę. To jest jedyna opcja.

Ł: Zaraz sobie do tego dojdziemy, bo będziemy mieli diagramy. Dla mnie to jest takie odstępstwo. Zgodzę się, że powinno być w docs, głównie markdown, ale trafią się też załączniki, więc nie bądźmy purystami, będzie PDF, PowerPoint, docs od biznesu, sample. To jest coś, co przyciągamy ze sobą jako taki artefakt, a nie jako rzecz, którą my wytwarzamy.

S: Dlatego mówiłem o plikach źródłowych, a to o czym mówiłeś, na nie się powołujemy jak najbardziej. Mam trochę mieszane uczucia, jeżeli chodzi o zip’y, bo to jest takie średnie. Rozwiązaniem może być Git LFS. Żeby 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 dokumentację, bo dobry diagram przepływu powie dużo więcej i lepiej niż opis tego w formie Word. Czyli słowno-muzyczny. O ile kiedyś był Mermaid JS, który był ok, ale po pierwsze był brzydki jak sześć nieszczęść, po drugie nie dało się go stylizować, po trzecie to działało w przeglądarce, więc nie do końca trzeba było tam robić cuda wianki w kontekście markdown’a. Ja odkryłem, nie wiem, może późno, dodatek do Visual Studio. Do całego zestawu plików. PlantUML

Ł: Tak, tylko że on nie jest tak naprawdę w Visual Studio, tylko open-source’owy projekt, który już żyje i żyje.

S: Ale fajnie się integruje z Visual Studio codem. To ważne. PlantUML. On umożliwia robienie naprawdę porządnych diagramów., stylizacje (mieliśmy dyskusję na starcie, że wyglądają jak sześć nieszczęść) Taka Java z lat 90tych.

Ł: To jest w Javie napisane.

S: Tak.

Ł: 2009 rok.

S: To blisko byłem. Możliwości, jeżeli chodzi o wszystkie pozostałe diagramy, stylizacje są ogromne. Jak to działa? Tutaj pojawia się odstępstwo od tego, co mówiliśmy. Wchodzimy w Visual Studio Code, klikamy, przegenerowuje wszystkie diagramy do katalogu out.

Ł: Czy to skrypt czy cokolwiek, bo tak naprawdę to jest narzędzie, czyli wyjściowo mamy plik z opisem naszego diagramu (tam jest coś a la….) Dobrze pamiętam?

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

Ł: Do robienia grafów. Troszeczkę można w niektórych miejscach porównać.

S: W sumie racja.

Ł: W niektórych ten ask i art, o których wspomnieliśmy przy GraphQL, raczej przy grafowych bazach.

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

Ł: Dobra. Czyli z jednej strony masz plik wejściowy i możesz sobie potem z tego wygenerować diagram, brzydki jak noc na dzień dobry.

S: Ale można go stylizować.

Ł: Tak. Znaczy wygląda gorzej niż Enterprise Architect, więc dla mnie to już jest wyczyn.

S: Zgadzam się. Ta Java, te szare kolory, przycięte. Ale też wynika częściowo z tego, że sam PlantUML ma standaryzacje pewnych kolorów, jak HTML – ma te kolory nazwane. I te kolory są brzydkie jak sześć nieszczęść.

Ł: Dla mnie to jest trochę wada, bo wprowadzamy kolejne do stosu narzędzie. To jest wada i zaleta. Zależy jak kto na to popatrzy. Do grafiki. Znajdzie się dużo tradycjonalistów, którzy chcą przeciągnąć kreskę w Visio, Draw.io czy innym narzędziu.

S: O ile byłem fanem Draw.io, to jednak on generuje, trzeba ten plik gdzieś trzymać, ściągać go na stronę. [L] Możesz go sobie ściągnąć i zapisać. Wiem, workflow jest spaprany.

S: Upierdliwy.

Ł: Tak, ale ludzi to stosują. I też nie narzekają na to.

S: Może nie znają alternatyw.

Ł: Tak.

S: Też stosowałem, ale po PlantUML do niczego innego już nie wrócę. Mermaid’a porzuciłem też kompletnie.

Ł: Dobra, to jest Twoje. Ja tak patrzę dla mnie najważniejsze to: nieważne w czym rysujesz, tylko niech ten plik źródłowy znajdzie się w tym Repo.

S: Tak.

Ł: Z czego generujesz. Wiem, że ten PlantUML będę chciał dzięki Tobie zobaczyć, może oświecę nim kogoś albo skażę go na niego. Zobaczymy jaki będzie werdykt po jakimś czasie używania. Jeżeli chodzi o diagramy (to jest bardzo ważne, widzę, że sobie nawet zapisałeś w notatkach) to wyjaśnia więcej niż tysiąc słów. Zapisz ten plik źródłowy razem z nim, wygeneruj go tak, żeby pojawił się na stronie. Jeżeli mówimy o obrazkach, to przydałoby się powiedzieć, jak je wstępnie rysować.

S: Wyjaśnij pytanie.

Ł: Jak dobrze narysować diagram? Jak złapać dobrze kontekst w diagramie?

S: O to Ci chodzi.

Ł: Tak.

S: Dobrze. Dochodzimy do tego, co jest de facto kluczem dokumentacji. Szczególnie osoby techniczne gubią ten clue. To co mówimy w ogóle w IT, że jest kontekst królem, do dokumentacji też się odnosi. Pamiętajmy, że jest coś takiego jak C4, całe podejście do dokumentacji kultury systemu.

Ł: Do wizualizacji.

S: Inaczej: do spojrzenia co usunąć, czego nie usuwać. Co powinno być na którym obrazku.

Ł: Znaczy tak, bo oni sami to nazywają jako model dla wizualizacji softwareowej architektury.

S: Tak, bo to się często widzi w dokumentacji; otwieramy dokument i na starcie mamy zejście na bardzo niskie szczegóły. A de facto, to jest to co mówi C4. Pierwszym kluczem jest kontekst: co to robi, do czego jest.

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

S: Dokładnie. Co robi, po co jest, jak żyje, ogólnie z jakim „zwierzęciem” mamy do czynienia.

Ł: Rzućmy przykład, bo mi się podoba. To jest dla systemu bankowego. My piszemy system transakcyjny i go dokumentujemy, gdzieś z boku mamy np. system e-mailowy do wysyłania powiadomień i innych rzeczy, a z drugiej strony mamy core-banking na jakimś main frame. Więc umieszczamy nasz system w kontekście tego ekosystemu, z którym pracuje.

S: Tak. Idąc poziom niżej, schodzimy na poziom konteneru, czyli jak się komunikujemy i powiedzmy, takie duże bloki.

Ł: Grube moduły w naszej aplikacji.

S: Tak.

Ł: To rzućmy jakimś przykładem. Grubym modułem będzie baza danych, jakieś mikroserwisy, każde z osobna, jakiś frontend, SPA, mobilna aplikacja, Api application. Czyli jesteśmy na poziomie pojedynczych dużych modułów, które możemy wyszczególnić.

S: Tak. Potem schodzimy sobie na komponenty. Czyli generalnie można powiedzieć, moduły naszych klas. Porównanie folderów w solucji.

Ł: Niektórych folderów. Jak mamy jakąś http api to mogą być w Dotnecie kontrolery, 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.

S: Na końcu mamy zwykły kod, do którego ja z reguły nie schodzę, bo jest kolejny element, jeśli chodzi o dokumentacje, to znaczy „dokumentacja jest kosztem”, jej utrzymanie jest drogie. Najgorszą dokumentacją jest nieaktualna dokumentacja. Ostatni punk, dziesiąty. Pamiętajmy, że są dwa typy dokumentacji: tak samo jak są dwa kubernety naszych odbiorców.

Ł: Typy dokumentacji, typy odbiorców jest chyba lepszym określeniem.

S: Jedno implikuje drugie. Pierwsze to jest techniczne, o którym z reguły pamiętamy, a drugi to jest biznesowe, czyli danie kontekstu co ten system robi, jak robi, jakie są procesy biznesowe, jakie case’y realizuje, bo to też jest bardzo ważne. To, żeby nowy deweloper mógł się ogarnąć w naszym workflow, który ma odpalić, jak się to mapuje. Pamiętajmy, że ten wstęp biznesowy, który powinien dobry PO zrobić, to też powinno być elementem dokumentacji. Na samym starcie przede wszystkim mamy taki C level skrót całego systemu, czyli pół strony opisu, który mówi…

Ł: Kontekst i co to w ogóle robi.

S: Tak. Dokładnie.

Ł: Co do biznesowej, bo jest problem, bo troszeczkę powiedzieliśmy o analizie, ja też się łapałem za to. Druga rzecz, że często jest jeszcze taka klasyczna analiza biznesowa, gdzie Enterprise Architecting i inne rzeczy się lepiej sprawdzają często lepiej niż podejście techniczne, które tutaj opisaliśmy.

S: Zgadza się. Przy dokumentacjach na skalę korporacji to musi jak najbardziej być.

Ł: Na skalę biznesową, kiedy analizujesz, kiedy taki rasowy analityk biznesowy wpada, dokumentuje proces i inne rzeczy, zbiera wymagania.

S: 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 naprawdę się opłaca.

Ł: Może inaczej, z drugiej strony. Pracowałem z ludźmi, którzy umieli w Enterprise Architect’ie, w narzędzia do zbierania określenia wymagań, i na przykład stamtąd przygenerowanie ładnego Worda do biznesu tak było kliknięcie. Sam z takimi paroma osobami pracowałeś.

S: Zgadza się.

Ł: Potrafiły spisać wymagania i z tych wymiocin, które znajdowały się w Enterprise Architect’ie nagle generowała się dokumentacja, która była do użytku potem, do akceptacji biznesu, czy potem przekazania do, już jako wejście do developmentu, wymagań.

S: Została nam jeszcze jedna ważna dyskusja, która obecnie zaczęła się toczyć. Markdown kontra AsciiDoc.

Ł: Powiem prosto: aktualnie markdown stał się takim quasi standardem, przyzwyczailiśmy się do jego stosowania.

S: Dobrze, że powiedziałeś „quasi”, bo markdown ma akurat tyle dziur na standaryzację.

Ł: Wiem. Dlatego użyłem słowa „quasi” bo mamy ileś jego odmian, tudzież smaków, przyprawione Githubem, przyprawione czym innym.

S: I to jest jego najważniejszy problem. Jaka jest podstawowa różnica? AsciiDoc jest taką dość konkretna specyfikacją, ma dużo więcej feature’ów, ma takie opcje jak ustawienia szerokości, itd. Wszędzie tam, gdzie w markdown, gdzie robimyfallback na html’a wstrzykiwanego, co nie jest idealne, to Ascii ma to bardzo ładnie ogarnięte. Ma dużo więcej feature’ów. Jego problemem jest to, że domyślnie nie jest renderowany i mało co go wspiera na wejściu. Czyli jak mamy pliki w AsciiDoc’u, to jest już trochę gorzej.

Ł: Nie. Dla mnie to jest popularność tego. Jeżeli pójdziemy na losową konferencję na temat developmentu i zapytamy się iluś osób co to jest markdown, a ile osób słyszało o AsciiDoc. Domyślam się wyniku.

S: Tak. Jedno ALE. W dokumentacji AsciiDoc zyskuje sporo użycia. Coraz częściej się go zauważa.

Ł: Ja bym teraz rozróżnił jedną ważną rzecz. Powiedzieliśmy sobie o naszej wewnętrznej dokumentacji. Jest sobie pozycja tzw. „technicznego pisarza” (ja to się śmieję po polsku) w różnych organizacjach, który pisze techniczną dokumentację dla klienta zewnętrznego. I tak naprawdę ta osoba musi być eks techniczna, musiała rozumieć, co pisała i tam korzysta się z zupełnie innych formatów. Taki AsciiDoc i jest jeszcze parę innych rozwiązań do spisywania i generowania publicznej dokumentacji. To jest zupełnie inna kwestia. Ja rzucę ciekawostkę np. z Microsoftu. Cały Azure na przykład, teraz Dotnet też na to przechodzi, jest pisane w Repach Githubowych, w Markdown, Microsoft Flavored Markdown.

S: Tak, i z dużych plusów, jak się na te Repa wejdzie, to strona automatycznie przełączy się nam na język polski.

Ł: Tak, to jest duży plus. Chodzi o to, że dali cały tooling tam, jest plugin do Visual Studio Code, żeby ładnie renderować sobie lokalnie tę dokumentacje. I mają taki cały system, który wy sobie zrobiliście teraz, pisałeś o nim przy swoim projekcie, do mikrodokumentacji.

S: Można też zgłaszać PR’y, itd.

Ł: Z jednej strony mamy takie standardy jak AsciiDoc, przeznaczone stricte do pisania. Moglibyśmy w LaTeX-u również pisać, jak popatrzysz na generowanie. Z drugiej strony szybkość pisania.

S: Tak.

Ł: Ja bym jeszcze dorzucił jedną rzecz: styl pisania w środku takiej dokumentacji, bo ludzie na siłę piszą okrągłe zdania.

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

Ł: Raczej: keep it simple stupid. Tak samo co do dokumentacji.

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

Ł: W Polsce jest jeszcze Jasnopis.

S: Nie korzystałem.

Ł: Też jest taka usługa.

S: Może być. Dla nas jeszcze ważna dyskusja, która się pojawiła, to kto pisze dokumentację. Często jest tak i z tym się spotykam, że jedna osoba pisze dokumentację, często jest to leader albo PO.

Ł: Ktoś, kto „wygrał” pisanie dokumentacji .

S: Wygrał, przegrał, różnie może być ;) My mamy podejście takie, że jednak pisze cały zespół.

Ł: To jest jak z ADRami – Ty podniosłeś, Ty tworzysz ADR’a.

S: Tak, nawet do tego stopnia, że jak mamy jakiś dokument, to rozbijamy go na działy i w tym momencie to są taski do wzięcia przez każdego.

Ł: To tak jak powiedzieliśmy o dokumentacji samego potem tego, co mamy w bebechach. To już powiedzieliśmy, że dokumentacja powinna iść z pull requestem.

S: Tak.

Ł: Więc jest się jednoznacznie wskazanym wtedy. Można powiedzieć, kto pisał dany kawałek.

S: Jasne. Dobra, podsumujmy to.

Ł: Wiesz co, może jeszcze problemy? W szczególności od strony Repo, bo jest jeden problem, który jakość przemilczeliśmy, w szczególności Ty.

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

Ł: Dla danego release’u.

S: Tak. Jedyna opcja, jaką na razie mam wykombinowaną po prostu, to jest zbieranie tego z artefaktów, ale nie ma automatyzacji tego, jest co najmniej słaba. Niestety.

Ł: Dobra. To co, podsumowujemy?

S: Mój pierwszy to jest PlantUML. Zachęcam do diagramów, bo zrewolucjonizował moje podejście do robienia diagramów.

Ł: Diagram as Code. Chciałbym, żeby było coś wbudowanego w Github’a i Bitbucket’a, bo wtedy byłbym szczęśliwym człowiekiem.

S: Tam były jakieś podejścia.

Ł: Znaczy, żeby coś się wystandaryzowało w ramach Repo do rysowania. To byłoby super, ale podsumowujmy. Diagram as Code, tak? Można sprawdzić, co Szymon mówi z PlantUML. Ja się jeszcze pod tym nie podpisuję. To nie jest moja twarda rekomendacja. Do diagramów tak. Róbcie diagramy.

S: Wszystko w Repo. O tym nie trzeba już chyba przekonywać. Wszystko leci, łącznie z odpowiedziami u klienta.

Ł: Następnie: Markdown nie gryzie. Powiedzmy sobie, że pisanie nie powinno gryźć.

S: Zdecydowanie.

Ł: Jeżeli masz problem z pisaniem, to są tylko punkty. 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.

S: Co więcej, jak puszczamy to przez PR’y, to się nauczymy. To jest to, o czym mówił Stephen King „Pisanie jest mięśniem, który należy trenować”. Dobra, tyle. Kończymy.

Ł: Na razie!