Łukasz Kałużny: Cześć, słuchacie Patoarchitektów. Prowadzą Łukasz Kałużny…

Szymon Warda: I Szymon Warda. Jak zwykle linki do tego odcinka są na Patoarchitekci.io/13. O czym dzisiaj? Dzisiaj porozmawiamy o ADR-ach, czyli Architecture Decision Records. Znowu kręcimy się wokół tooli architektonicznych, roli architekta. Temat większy, wrócimy.

Łukasz Kałużny: Dobra, to może pójdźmy pierw przez to, co ostatnio czytałeś.

Szymon Warda: Tak, ja drugi raz z rzędu raport, tym razem Gartner. Gartner, mianowicie o rynku baz danych. Jak to wygląda? Parę interesujących informacji. Rynek jako taki w ciągu ostatnich dwóch lat rok w rok wzrastał o 13,18%, czyli stabilny wzrost, całkiem ok. Co jest ciekawe, to rynek chmurowych baz danych - wzrost 68%, czyli bardzo dużo. Ale co jest najciekawsze, 72% tego wzrostu stanowił Microsoft, oczywisty wzrost i uwaga - AWS. Kogo brakuje? Oracle’a. Jak mówimy o bazach danych, to Oracle z reguły jest dużym graczem, a tu go nie ma.

Łukasz Kałużny: Tak, inną rzeczą, która też właśnie na ten 2018 rok, że chmurowe rozwiązania stają się domyślną platformą.

Szymon Warda: Tak.

Łukasz Kałużny: Że tutaj to nie był on prem, ale domyślną, przy tej ilości wzrostu właśnie były to chmurowe.

Szymon Warda: Tak, nie oszukujmy się, tego wzrostu większość 3/4 to jest wzrost chmurowy, czyli chmura napędza ten wzrost. No ale to jest już naturalne, bo hostowanie dużych baz danych i dziwnych baz danych na on premie jest skomplikowane i wymaga dużej wiedzy organizacji. A co u Ciebie Łukaszu?

Łukasz Kałużny: Wiesz co, ja teraz za to, Ty raport, ja za to wywiad z ciekawą, najciekawszą branżą, do której się nikt nie przyznaje, czyli jest tutaj Pornhub Web Developer. I ciekawą dlatego, że jednak tam jest dużo ciekawych, rozwiązania w porno są wykorzystywane w dużej skali.

Szymon Warda: Ogromnej skali.

Łukasz Kałużny: Ogromnej skali. I jeżeli popatrzymy, gdzieś był joke, że 60% ruchu na media, serwisy azure’owych do przygotowywania materiałów właśnie pochodzi z tej branży. To taka ciekawa rzecz, gdzieś tam w inside gdzieś natrafiłem w necie, nie weryfikowałem go, ale jestem w stanie uwierzyć. Ale z całym wywiadem, co było ciekawe, bardzo pokazany stack technologiczny. Jest on prosty, bo PHP króluje w porno, jeżeli popatrzymy. I co jest pokazywane jako baza? Nginx, PHP, mySQL i memcached albo Reddit i to jest taka baza, z której korzystają. A dodatkowo korzystają z Varnisha, Elastic Searcha, Node.js, GO czy vertici.

Łukasz Kałużny: Ale ważne, stosują tylko to wtedy, kiedy jest faktycznie potrzebne. Sam raport jest cały dłuższy, bo mówimy tutaj jeszcze jest o JavaScripcie. Mowa na przykład o tym, że pozbywają się już jQuery i korzystają z takich lekkich frameworków jak Vue.js, więc warto przeczytać.

Szymon Warda: Tak, w ogóle te raporty pornhubowe, te wywiady techniczne, które publikują, są naprawdę wartościowe. Tak, strona, która często może być zbanowana w pracy, ale te rzeczy techniczne dobre są. Dobrze, to wracamy do ADR-ów. Zaczynamy jak zwykle. Dwa zdania, czym jest ADR?

Łukasz Kałużny: Będzie w jednym. Formalne dokumentowanie decyzji architektonicznych.

Szymon Warda: No i na formalne żeśmy stracili większość słuchających.

Łukasz Kałużny: To co to jest dla Ciebie, jak mówisz, że czepiasz się formalne.

Szymon Warda: Dla mnie to jest notatka o decyzji bardziej. Dużo mniej formalny, bo to formalne często ma takie dość negatywne konotacje. Ale zgodzę się z tym, co rozmawialiśmy wcześniej, trochę przed nagrywaniem, że to jest wprowadzenie elementu procesu.

Łukasz Kałużny: Tak.

Szymon Warda: Dobrze. W takim razie. Co w ogóle powinien zawierać ADR?

Łukasz Kałużny: Dobra, czyli tak jak powiedzieliśmy, jest to już notatka, więc ta notatka ma swoją ustaloną już strukturę i jest ona dość prosta: data, temat, problem, jakie opcje tudzież rozwiązania były dostępne dla tego problemu? Jaka opcja została wybrana? I ostatnia, bardzo istotna - czemu?

Szymon Warda: Tak. Dodam jeszcze, że tych template’ów jest w sieci dość sporo tak naprawdę, można wybierać. Ale to takie, które są wszędzie praktycznie.

Łukasz Kałużny: Tak.

Szymon Warda: Bo jak zwykle tam, gdzie pomysł, to implementacji jest bardzo, bardzo dużo. Dobra, to przejdźmy po kolei po każdej z tych sekcji.

Szymon Warda: Czyli co? Od daty zaczynamy? No jest to pole. Pierdoła. Ja jako datę wstawiam zawsze ten dokument, kiedy to powstało. To jest drugorzędne pole, bo to właściwie też mamy w GitHubie, potem będzie trzymane.

Łukasz Kałużny: No więc tak, można to robić, w zależności co stosujemy, stosować datę stworzenia dokumentu z systemu.

Szymon Warda: To lecimy po kolei. Kolejny temat.

Łukasz Kałużny: Temat i on nie zawsze będzie taki prosty, ale… Inaczej, z mojej perspektywy, bo to jest tak jak z nazywaniem rzeczy, niech on będzie po prostu prosty i mówi czemu, o co tutaj chodzi, żebyś już przeglądając taką notatkę wiedział od początku, po co to jest.

Szymon Warda: Ja jeszcze mniejszą uwagę na to daję, ponieważ ADR-y to są z reguły pliki tekstowe, proste pliki tekstowe, więc tam full text search działa fenomenalnie. I tak z reguły jak szukam jakiegoś tematu, to robię po prostu full text searcha po wszystkich dokumentach. Nie ma ich z reguły tysiące, więc to działa szybko. Co więcej, praktycznie każdy, każde repo hostowane online też ma full text searcha wbudowanego w plikach, więc nie spinajmy się, żeby to miało sens. Dobra, problem.

Łukasz Kałużny: I problem. To jest taka pierwsza już istotna rzecz.

Szymon Warda: Od tego się zaczyna.

Łukasz Kałużny: Tak, od tego się zaczyna. Czyli jako że jest to notatka architektoniczna, to opisujemy tutaj… Mamy do podjęcia jakąś decyzję. Przykładowo rzucając tutaj chcemy coś zmienić, dodać jakiś komponent, wykonać jakąś integrację, więc opisujemy odpowiednio ten problem. I co ważne, trzeba temu problemowi nadać kontekst z czego on wynika, gdzie jest umiejscowiony. I tutaj mieliśmy z Szymonem dobrą dyskusję, którą potem przytoczymy właśnie kiedy to pisać. Ale w kontekście całego, piszemy to w kontekście rozwiązania i organizacji. To są dwa konteksty, które muszą wystąpić przy opisaniu problemu.

Szymon Warda: Dobrze, użyłeś dwóch słów, które musimy trochę pogłębić. Mianowicie problem. Jaki problem? Bo ADR, nazwa jest architecture.

Łukasz Kałużny: Tak.

Szymon Warda: Jaki scope, jaki zakres tego architecture…

Łukasz Kałużny: Zakres, czyli rzecz, która wpływa nam na architekturę rozwiązania.

Szymon Warda: Bardzo ważne.

Łukasz Kałużny: Rozwiązania. To nie jest architektura aplikacji, ale patrzmy…

Szymon Warda: Ani systemowa.

Łukasz Kałużny: Systemowa, ale rozwiązania. Mieliśmy tutaj dyskusję o tym, czy wpisać na przykład rozwiązanie, że wybraliśmy team city jako rozwiązanie do continuous deploymentu. Jeżeli masz mikroserwisy, robisz X release’ów dziennie, jest to wpisane w Twój kontekst biznesowy, to wtedy jest to decyzja całego rozwiązania, ponieważ jest on wbrew pozorom istotnym elementem systemu, bo ciągle dostarcza nam coś do naszej aplikacji w kontekście jakiegoś projektu, który jest robiony. Za to release raz na 3 miesiące, a są takie rzeczy, to ma dużo mniejszy scope, więc to jest istotne. I wpisujemy tutaj wszystkie na przykład czynniki zewnętrzne, wszystkie biznesowe. I z czynników takich technicznych, które się zdarzają, mogą być rzeczy, które są absurdalne, ale są wymuszone z zewnątrz, na przykład jakąś ogólną polityką, która jest wprowadzana w firmie albo uspójniająca. I takim przypadkiem absurdalnym naprawdę, ale z którym się spotkałem, jest wymiana wszystkich baz relacyjnych na Oracle’a, bo została podjęta decyzja w firmie, że jest uspójniana, są uwspólnione bazy relacyjne do jednego typu preferowanego, którym był, nie wchodząc dlaczego, Oracle. I to była rzecz, którą tutaj w kontekście notatki decyzyjnej trzeba napisać i tyle. I to jest problem.

Szymon Warda: Ale w ogóle nasze projekty, które realizujemy, nie są zawieszone w przestrzeni pustej. To samo nas czeka generalnie z całym .Net frameworkiem. To samo nas spotkało z całym Silverlightem. Te czynniki zewnętrzne z reguły właśnie one będą takie, że ok, wydarzyło się, co teraz? One są tym zapłonem do dalszych decyzji dużych.

Łukasz Kałużny: Tak, jedne to są technologiczne. Innym jeszcze technologicznym, możemy powiedzieć, że będą problemy wydajnościowe i będziemy wymieniać komponenty. Ze względu na to, że doszliśmy na przykład, taki przypadek, ktoś wybrał Rabbita i w pewnym momencie już mu nie wystarcza i chce przejść na Kafkę i to będzie… Chciałby przejść na Kafkę, czy na jakieś szybsze rozwiązanie, więc powinniśmy opisać problem, że jest to problem wydajnościowy z całą platformą i musimy podjąć następujące…

Szymon Warda: Tudzież nawet inny. Na przykład używamy Rabbita i wchodzimy teraz w Managed Rabbita, czyli zarządzanego, czyli nagle z on premisów przechodzimy na usługę. To niby nie jest zmiana techniczna w żaden sposób, tylko bardziej biznesowa. To też powinniśmy tłumaczyć, jakie są tego konsekwencje.

Łukasz Kałużny: Tak więc są i inne będą takie bardzo życiowe, zewnętrzne czynniki, to mogą być różne compliance’owe. Na przykład wprowadzenie GDPR RODO, bardzo potężna zmiana w systemach, jeżeli mamy dane osobowe.

Szymon Warda: Szczególnie w logach, bo tam często znajdujemy takie smaczki.

Łukasz Kałużny: Tak. Inne przypadki? Biznes zażyczył sobie nowej integracji z jakimś zewnętrznym partnerem biznesowym, dwustronną, jednostronną, więc trzeba tutaj podjąć, jest to decyzja do podjęcia, więc jest to problem do opisania.

Szymon Warda: Tak. Trochę zahaczyliśmy o wytłumaczenie czym jest kontekst, ale jeszcze nam paru rzeczy brakuje. Czy coś chciałeś dodać jeszcze?

Łukasz Kałużny: Wiesz co, kontekst chyba, zastanawiam się, bo…

Szymon Warda: Tam jeszcze są ograniczenia. W sensie na przykład czego nie możemy zrobić, co możemy.

Łukasz Kałużny: Tak, jeżeli mamy kontekst, mamy też granicę i to zawsze jest. Tylko to jest pytanie, czy nie powinno być to filozoficzne, czy nie powinno to być w kolejnych elementach ograniczenia? Bo mogą być ograniczenia, które zostały na nas przy problemie już narzucone z zewnątrz. Może być to budżet, czas realizacji i wtedy możemy… Ograniczenia są zależne, czy są narzucone nam już razem z kontekstem.

Szymon Warda: Tak, one tworzą kontekst, czyli cały ekosystem wokół się znajduje, nie tylko techniczne, ale też biznesowy, ogólnofirmowy. To idziemy dalej. Jakie opcje były rozważane? I to jest dla mnie osobiście bardzo ważna sekcja.

Łukasz Kałużny: Czyli opcja jest bardzo istotnym, czyli jest to wypisanie opcji, jakie są brane pod albo były brane pod uwagę. I teraz ważne, warto zrobić, pokazać, że nie wypisujemy tego z pamięci i tak wybierzemy jedno preferowane, bo lepiej już wtedy nic nie wypisywać i potem w kolejnej sekcji po prostu powiedzieć wprost, że na podstawie X rzeczy nie sprawdzaliśmy innych opcji i tyle, tylko podjęliśmy autorytatywnie albo zespołowo taką decyzję, że robimy co, a robimy coś i nie rozważaliśmy innych opcji. Ale jeżeli już je rozważamy, to nie powinno być to listowanie.

Szymon Warda: Zgadzam się. Jeszcze dorzucę, niektóre decyzje podejmujemy wiedzą ekspercką. Nie oszukujmy się.

Łukasz Kałużny: Tak, tylko ważne to wtedy wypisać opcje i że podjęliśmy, znając X, Y, Z podjęliśmy taką decyzję, a jeżeli nie, to przy małych zmianach przegląd dokumentacji. Jeżeli wprowadzamy jakiś komponent, który wpływa na architekturę, to przegląd dokumentacji, czyli dobry research. Ewentualnie robienie przy większych zmianach jednak albo takich minimalnych, tak zwanych brudnych, szybkich PoC-y, żeby coś sprawdzić to. Jeżeli robimy już taki minimalny brudny PoC, to chociaż zachowajmy tą przyzwoitość, że weźmiemy sobie dane, które będą produkcyjne, wielkości produkcyjnej, bo często jest robione, że przy PoC-ach testujemy to na za małych danych, a potem dostajemy kulą, dostajemy kulą albo odcina coś, urywa nam rękę potem na produkcji.

Szymon Warda: Czyżbyś nawiązywał do naszego odcinka o fuckupach?

Łukasz Kałużny: Też, też i parę osób może się przyznać po wyborach, takich decyzjach, że nie brało kontekstu wielkości danych produkcyjnych. Więc często warto przy wybraniu tych opcji je faktycznie przetestować. Więc powinno to też zaczynać inne części procesu wyboru technologii, jeżeli jakąś wprowadzamy albo zmiany.

Szymon Warda: Pamiętajmy, że też niektóre rzeczy możemy oceniać na podstawie po prostu braku umiejętności w zespole.

Łukasz Kałużny: Tak i jest to bardzo prosta decyzja.

Szymon Warda: Oczywiście.

Łukasz Kałużny: Czas, budżet, kompetencje.

Szymon Warda: Tak, kwestie prawne, brak odpowiednich licencji i tak dalej. Jak najbardziej może być. Chociażby brak załóżmy data center w danym kraju.

Łukasz Kałużny: Tak, ale właśnie to, co powiedziałeś, też możemy w listowaniu szybko odciąć i potem w następnej sekcji.

Szymon Warda: Tak.

Łukasz Kałużny: Czyli czemu, możemy to właśnie zacząć odcinać. Czyli wziąć, zdefiniować szczerze czemu taka a nie inna decyzja została podjęta, co miało na nią wpływ. I jeżeli jakieś rzeczy odrzucamy a mieliśmy wypisane, wybrane w opcjach więcej takich rzeczy, w Options, to po prostu szczerze w jednym zdaniu, w dwóch, trzech słowach dlaczego je odrzuciliśmy. I to może być: nie mamy licencji, nie mamy budżetu, nie znamy się na tym, a to wiemy jakie będą się wiązały z tym problemy, ponieważ używamy na co dzień, więc wybieramy tą opcję.

Szymon Warda: Jasne. Ja często robię tak, że na poziomie opcji, jeżeli coś odrzucamy na poziomie jednego zdania, załóżmy brak licencji albo brak pewnego feature, którego potrzebujemy, to na tym poziomie notuję czemu odrzuciliśmy, czyli robię takie przesianie. A w czemu już taką mniejszą grupę, ostatnie już bardziej dogłębne, czemu akurat te opcje nie weszły, jeżeli wymagają większego sprawdzenia np. PoC-a, to już bardziej będzie w czemu ujęte. To przechodzimy płynnie, opcja “czemu”.

Łukasz Kałużny: Tak.

Szymon Warda: Czyli czym jest ta sekcja.

Łukasz Kałużny: Szczerym napisaniem czemu taka a nie inna decyzja. Bardzo proste. Tylko szczerze i tak, żeby ktoś kto to przeczyta, nie zadawał nam potem pytań, tylko mógł wiedzieć w tym kontekście naszego problemu, w tych granicach, o których wspomniałeś, że mógł dowiedzieć się czemu podjęliśmy taką, a nie inną zmianę w architekturze.

Szymon Warda: Jasne, ja się dorzucę, bo to jest taka jedna z technik, bo czasami napisanie czemu jest, nie jest takie trywialne. Ja lubię patrzeć na poziomie wektorów, w których się optymalizuje systemy. Możemy pokazać wydajność, skalowanie, czas dostarczenia i UI Experience, koszty utrzymania i tak dalej. I tak spojrzenie generalnie, jak wybierzemy którykolwiek z tych wektorów, to zawsze zaistnieje wektor, który jest dokładnie odwrotny. I jasne podpisanie generalnie, że: okej, w tej decyzji kierowaliśmy się po prostu kosztem albo czasem dostarczenia rozwiązania. W tym momencie wiemy, że jak optymalizujemy czas, no to sorry, jakość może nie być najlepsza albo wybraliśmy, na przykład koszty mogą być bardzo wysokie. I to jest taka fajna technika, która pokazuje, w którym kierunku, co było naszym celem, a co dokładnie nie było naszym celem. Przydaje się. Polecam.

Łukasz Kałużny: Tak, i ja bym jeszcze dorzucił jedną rzecz do czemu. Jeżeli mówimy, bo ADR ma być z założenia lekkie i nie ma być upierdliwe w implementacji.

Szymon Warda: Tak.

Łukasz Kałużny: Ale jeżeli coś ma być długie w ADR-ach, to właśnie czemu? Bo powinno być to najbardziej rozwinięte. A jeżeli mówimy o problemie, on nie musi być długi, ale musi być jasno zdefiniowany.

Szymon Warda: Tak, zgadzam się jak najbardziej. Taki fajny przykład, który załóżmy a propos czemu i a propos decyzji, to mieliśmy to, że: jaka decyzja? Potrzebujemy tracingu, potrzebujemy monitorowania. Dodaliśmy Application Insights, działa wszystko fajnie. Totalnie nie optymalizuje nam to kosztów, więc teraz kolejna decyzja, przechodzimy na Grafanę, która daje lepsze alerty i tak dalej. Dlatego właśnie te wektory są takie ważne i czemu te decyzje zostały podjęte? Bo te wektory mogą już być nieopłacalne po roku albo po prostu zmienił się ekosystem, w którym się znajdujemy. Dobra, trochę ruszyliśmy temat tego, jak stosować. A co robimy z tematem, jak żadnej decyzji nie podjęliśmy czy odrzuciliśmy inicjatywę?

Łukasz Kałużny: Wiesz co, jeżeli jest coś odrzucone i zostaje niezmieniające, powinniśmy gdzieś to przechować. Czyli tak naprawdę nie kasujemy, nie zapominamy o tym. Zostawiamy, bo to też ma wartość. I potem w kontekście przeglądania ma. I chyba przejdziemy teraz płynnie do?

Szymon Warda: Gdzie trzymać ADR-y.

Łukasz Kałużny: Właśnie. I to jest gdzie trzymać, bo trzeba gdzieś je trzymać. I tutaj w sumie sami trochę się wysypaliśmy po drodze, bo mówiliśmy o repo. Naturalną rzeczą nie jest żaden confluence, SharePoint czy inna rzecz…

Szymon Warda: Ani strony wiki.

Łukasz Kałużny: Ani strony wiki, ale po prostu zwykłe, zwyczajne repo. I taka notatka, taki ADR powinien być trzymany w postaci po prostu markdowna, zwykłego pliku markdownowego, który jest bardzo prosty do edycji.

Szymon Warda: I ładnie wygląda.

Łukasz Kałużny: Tak, ładnie… Tutaj…

Szymon Warda: Ma stylowanie.

Łukasz Kałużny: I tu wychodzi nasze podejście, że ma, tak, po prostu ma stylowanie i dla nas jest to wygodne z naszego przyzwyczajenia akurat do pisania.

Szymon Warda: I czytelne, co ważne, te nagłówki jednak wiemy gdzie się zaczyna która sekcja i tak dalej.

Łukasz Kałużny: Tak, więc to. I jeżeli macie repo, czyli trzymamy to w repo, trzymamy to w repozytoriach firmowych.

Szymon Warda: Tak.

Łukasz Kałużny: I tutaj może zaraz ktoś mnie złapać: ale w którym repo?

Szymon Warda: Dość ważne.

Łukasz Kałużny: Tak, dość ważne,w repo. I mamy tutaj takie przypadki. Jeżeli nasze repo z aplikacją zawiera na przykład dokumentację, bo coraz częściej się tak zdarza i jest ona w kontekście, jeżeli to jest monolit, mamy jedno duże repo, to może się okazać, że tam i mamy dokumentację też trzymaną na przykład w markdownie, to tam jest dobrze wprowadzić ADR-y, po prostu osobny folder na ADR-y gdzieś w folderze z dokumentacją.

Szymon Warda: Tak.

Łukasz Kałużny: Tam może być. Innym przykładem, jeżeli są mikroserwisy to…

Szymon Warda: Lub serwisy.

Łukasz Kałużny: Lub serwisy, tak, mikro, to ludziom od razu się kojarzą z dużą ilością repozytoriów, więc dlatego tego użyłem.

Szymon Warda: Tłumacz się, tłumacz.

Łukasz Kałużny: Tłumacz. To przy mikroserwisach często tudzież serwisach mamy często jakieś ogólne repo projektowe i ADR-y w ramach tego kontekstu powinny tam trafić. A jeżeli nie mamy, to są przykłady na rynku, że zakładamy ogólne takie repo company white, takie ogólnoorganizacyjne, ogólnofirmowe, tudzież repo zespołu architektonicznego.

Szymon Warda: Ja bym doprecyzował, że z reguły dostępność repo powinna… To gdzie umieszczamy ADR, scope tego repo, w którym umieszczamy ADR, powinien być taki sam jak scope naszej decyzji. Czyli jeżeli decyzja jest ogólnofirmowa, repo ogólnofirmowe. Jeżeli jest projektowa, to repo projektowe i trzymamy się tego. Dobra, ale czemu właściwie repo? Bo do trzymania markdownów moglibyśmy używać czegokolwiek innego.

Łukasz Kałużny: I wiesz co, czemu tak naprawdę repo? Z bardzo prostej przyczyny, ADR-y możemy traktować jak wytwarzanie kodu.

Szymon Warda: Co nas prowadzi do?

Łukasz Kałużny: Możemy robić tutaj pull requesty przykładowo. Czyli tworzyć takiego ADR-a i umieszczacie go w repozytorium, opisujecie to i możecie zrobić pull request właśnie merge’ujący to do mastera i dać to do review. Czyli ktoś może tutaj o tym decydować.

Szymon Warda: I co jest dla mnie mega krytyczne? To jest to, że okej, można dać łatwy feedback, co jest dobrze, co jest niedobrze, ale też widzimy, kto się zgodził, kto się nie zgodził, kto rzucił okiem, kto przeczytał i tak dalej.

Łukasz Kałużny: Kto zaakceptował. Można nawet ustawić, jeżeli mamy wymaganie, że przynajmniej dwie albo trzy osoby mogą to zreviewować, jeżeli nasze repozytorium na to pozwala. Jest to wtedy świetne. No i możemy trackować to w ogóle, decyzje w czasie, to jest piękne, jak wykres narastania decyzji w czasie.

Szymon Warda: Tak, zgadza się jak najbardziej. My też zrobiliśmy tą opcję, że traktujemy takie ADR-y, takie drafty ADR-rów jako tematy, które powinny być przedyskutowane przez Architecture Board. Ktoś po prostu wrzuca prosty plik, na przykład załóżmy zmieniamy bibliotekę Reacta na cokolwiek innego albo coś w tym stylu, albo AWS, GCP i tak dalej. Co robimy? I to jest obgadywane i ustalane i to idzie jako oficjalny dokument.

Łukasz Kałużny: Tak i fajną jeszcze rzeczą, że przy tych ADR-ach i pull requestach, bo to jest normalne jak code review, więc można dać komentarze i inne rzeczy i tam prowadzić całą dyskusję, flame war, w zależności od tego, jaką mamy kulturę.

Szymon Warda: Tak. I nie wprowadzamy dodatkowego źródła komunikacji, bo to też jest bardzo dobra praktyka.

Łukasz Kałużny: Tak, mamy standardowe narzędzia.

Szymon Warda: Dokładnie i wszyscy widzą u siebie. Jak kogoś dodamy, to będzie to widział u siebie, żeby to zreviewować. Dobrze. Jak jesteśmy przy repo, przy markdownach i tak dalej to do nas dochodzi od razu często też, co widzimy, toole do ADR-ów.

Łukasz Kałużny: Tak, jest sobie coś w szczególności dla Mac’owców, ADR-tools, który generuje template. I powiem, bez przesady, minimalizujmy tą ilość tooli, wystarczy Wam, z praktyki, wystarczy Wam po prostu markdown, który będzie oznaczony jako template.markdown, gdzie będziecie mieli wszystkie pola wypełnione plus jakieś tylko przykłady co tam ma być i jedno zdanie co ma się znaleźć znaleźć w sekcji + linki do best practices, jakiejś prezentacji, czegokolwiek, albo wrzucić tam też opis do linka ogólnofirmowego jak traktujemy ADR-y, jaki jest proces, koniec.

Szymon Warda: Tak. Co jest jeszcze dla mnie ważne? To jest to, że pamiętajmy, że większość narzędzi typu Azure DevOps i tak dalej, umożliwia edytowanie z portalu. Więc jak wprowadzimy tu link, to odcinamy możliwość tworzenia z portalu, bo to nie będzie zgodne. A coraz więcej dobrych PO i tak dalej, też takie inicjatywy może mieć.

Łukasz Kałużny: Tak. Więc zostawiamy, po prostu korzystamy z tego co mamy, repo, żadnych dodatkowych rzeczy, edytor, Git, koniec. To co kto lubi.

Szymon Warda: Tak. Nie twórzmy dodatkowych barier wejścia. To nie ma żadnego sensu. Sami ich nie lubimy, więc nie twórzmy. Dobra, złote zasady.

Łukasz Kałużny: Chyba najważniejsza - krótko, bo…

Szymon Warda: Tak.

Łukasz Kałużny: Ja użyłem słowa formalne i teraz to się będzie kłócić. Tak, bo dla mnie formalne, bo jest to proces, który przyjmujemy jako kulturę.

Szymon Warda: I z tym się zgadzamy.

Łukasz Kałużny: Tak. I krótko. Jest sporo punktów i tutaj nie ma kwiecistego języka. To nie ma być piękne. Czyste, piękne, piękne z punktu widzenia inżynierskiego, czyli bullety wszędzie, punkty, krótko, zwięźle, na temat, zero rozpisywania się. Lepiej napisać 5 bulletów niż 5 pięknych zdań złożonych z niewiadomą ilością, że zaśniemy przy czytaniu pierwszego.

Szymon Warda: Ja często widzę tendencję u nas, wśród technicznych ludzi, że piszemy długie zdania złożone, nie bullety. Bullety są najlepszą chyba opcją.

Łukasz Kałużny: Proste, żołnierskie słowa.

Szymon Warda: Tak. Dokładnie. Dobrze. Co jeszcze możemy zrobić? Z fajnych rzeczy jeszcze jest to, że możemy… Co zrobić w sytuacji, jak nagle któryś ADR, który wydaje nam się po prostu błędny i chcielibyśmy zacząć rozmowę o tym?

Łukasz Kałużny: Tak, zakładamy buga i to jest właśnie wspaniałe, że traktujemy to jak trochę wytwarzanie software’u i zakładamy buga po prostu i przypisujemy do właściciela ADR-a, tudzież aktualnego właściciela projektu.

Szymon Warda: Repo tudzież do grupy. Co jest fajne? Że na większości repo możemy zdefiniować grupę automatycznych review’erów…

Łukasz Kałużny: Na podstawie ścieżek.

Szymon Warda: Ścieżek i tak dalej. Więc to automatycznie nam trafi. Nie, znowu nie tworzymy barier, robimy to, próg wejścia jak najprostszy. Czemu? No bo jak ADR-y będą niezmienne i nie będziemy ich zmieniali, to ludzie zaczną po prostu je olewać i one będą nieaktualne. A wszyscy kochamy nieżywą dokumentację. Dobra, ale tak mówiliśmy co, jak, co się dzieje wokół tego. A w ogóle po co, tak z czystego inżynierskiego podejścia, czemu pisze ADR-y?

Łukasz Kałużny: Wiesz co, po pierwsze zmuszamy się do myślenia, czemu podejmujemy taką a nie inną decyzję. I potem na ślepo nie będziemy podążać za taką decyzją, pomimo faktu na przykład, że jest mylna. Bo często tak się zdarza. Ja na przykład za to kocham, kocham podejście projektowe Prince, które mówi o zachowaniu ciągłej zasadności projektu i rozwiązania. Więc ADR możemy też tak traktować, że patrzeć na to, czemu podjęliśmy i potem przy takim review tego, co się dzieje, zobaczyć, czy to ciągle ma sens. Inna rzecz, że jeżeli potrzebujemy, mamy pełen zestaw takich powodów, tam powinien być wypisany, dlaczego coś zrobiliśmy tak czy inaczej. I dla mnie takim koronnym faktem, w szczególności przy rzeczach, które żyją długo, jest to dokumentacja, że coś miało sens w tym momencie czasu, w tym konkretnym kontekście. Bo często wychodzą takie kwiatki, że czemu wygląda to tak, a inaczej bym mógł to sparafrazować, ale już nie będę częstym pytaniem robotników, jak przychodzi jeden specjalista po drugim wykańczać nam mieszkanie. I może się wydawać, że w danym momencie czasu, teraz jak przeglądamy coś starego, że to były durne decyzje, a w tamtym czasie to był state of art. I to dokładnym przykładem będzie “co jest be”. Jak było to w kwiecie wieku, to była bardzo świetna decyzja.

Szymon Warda: Jasne. Czyli bronimy się przed tym na co narzekamy często przy procesach biznesowych, że one obrosły dodatkowymi IF-ami, warunkami, którymi często biznes podąża, one już nie mają w ogóle żadnego sensu. I absolutnie to samo dzieje się dokładnie też u nas w projektach, że na przykład robimy, korzystamy z jakieś narzędzia, bo tak zawsze było i ludzie mają tendencję do takiego zachowywania się. I zgadzam się jak najbardziej, przed tym trzeba się bronić. Dla mnie jeszcze jest taki czysto praktyczny, żeby nie tłumaczyć kolejnej osobie. Jeżeli ma się malutki projekt to okej, ta wiedza się niesie. Jeżeli przeskalujemy się na 2, 3 teamy do projektu, ta wiedza już się organicznie nie rozszerza tak dobrze.

Łukasz Kałużny: Tak, unikamy, przez ADR-y unikamy wiedzy plemiennej.

Szymon Warda: Tak, dokładnie, rozszerzamy, zapisujemy i to, co powiedziałeś, też dla mnie osobiście bardzo ważne, spisując rzeczy, automatycznie układamy je sobie w głowie. Samo zmuszenie się do spisania jest naprawdę wartościowe.

Łukasz Kałużny: Tak i tutaj przy małych zespołach tak, zawsze będzie miało to sens, bo to są dokumenty dla potomnych.

Szymon Warda: Tak, i to jest właśnie bardzo ważne.

Łukasz Kałużny: Albo dla Ciebie w przyszłości.

Szymon Warda: Tak, dokładnie.

Łukasz Kałużny: Dobra, co dalej, Szymonie?

Szymon Warda: Kiedy pisać ADR-y w ogóle? Jak wmontować ADR-y w proces, który tworzymy?

Łukasz Kałużny: Dobra, dla mnie jest tylko jeden moment, kiedy można je napisać. Jest to, kiedy musimy podjąć tą decyzję i zaimplementować, czyli robimy je na starcie przed implementacją czegokolwiek.

Szymon Warda: Czyli nie podjąć, tylko dopiero przymierzamy się do podjęcia.

Łukasz Kałużny: Tak, przymierzamy się podjęcia i wtedy już powinien powstać draft.

Szymon Warda: Tak.

Łukasz Kałużny: I być może porzucamy decyzję, to przenosimy go do katalogu odrzucone, w zależności jak go tam ładnie nazwiemy.

Szymon Warda: Tak, zgadzam się w zupełności. I dlatego ja dawałem tą definicję ADR jako notatka, bo moja pierwsza wersja ADR-a, jak wpisuję, to jest dosłownie: otwieram Notepad++ i tam wypisuję linki, rzeczy robię. To jest mój notatnik do całego researchu, który prowadzę wokół tej sprawy.

Łukasz Kałużny: Tak i na końcu, bo tego nie powiedzieliśmy, w niektórych są notesy. Czyli w niektórych ADR-ach można, możecie, jeżeli robicie taki research uczciwy, możecie zostawić linki, notesy, wszystko, co linkuję po tych artefaktach naszego researchu, PoT-sach i innych rzeczach.

Szymon Warda: Tak, tak. Dobrze. Z uwag - nie starajmy się robić ADR-ów po fakcie, bo to jest wygładzenie historii.

Łukasz Kałużny: Tak, zgodzę się, bo tam już racjonalizujemy naszą decyzję.

Szymon Warda: Tak, to jest wstecz. Jak w tym momencie to już nie ma sensu tego robić. Co więcej, nie przekładajmy ADR-a na później, bo nigdy nie będzie czasu, żeby go napisać dobrze. Skupmy się na tym, żeby on był, niż żeby był idealny. Dość ważne. A co więcej, im wcześniej go wrzucimy do jakiegoś repo albo do PR-a, tym wcześniej zaangażujemy całą organizację ludzi. A to właśnie to zaangażowanie jest bardzo, bardzo ważne. To jeden z krytycznych elementów, to szerzenie wiedzy właśnie nie plemiennej. Nie to, że kolega obok usłyszał, że o czymś myślimy, coś badamy. Cały projekt ma wiedzieć, a może nawet cała firma. Dobrze, jakieś good practices.

Łukasz Kałużny: Wiesz co, pierwsze, tak jak powiedzieliśmy sporo, jeżeli już mówimy, wchodzimy w środek, to linkowanie między ADR-ami, bo takie repo daje nam po prostu, wskazujemy tam w takim markdownie sobie jako link ścieżkę do innego pliku i działa świetnie. Czyli linkowanie w środku między ADR-ami, wskazywanie, jeżeli wprowadzamy zmiany. W szczególności jeżeli zmieniamy decyzję jakiegoś ADR-a, który już był, to wtedy warto albo że inny ADR miał wpływ i na niego się powołujemy, że zgodnie z tamtym researchem wychodzi na to, że mamy bardzo zbliżony problem albo posiedliśmy już kompetencje, więc wykorzystujemy tamto podejście i to, co się tam znalazło.

Szymon Warda: Ja z takich good practices dorzucę to, że od razu zaznaczam osobę, która ma zrobić ADR-a. W sensie ta osoba, która wychodzi z inicjatywą, ta tworzy dokument i ona jest odpowiedzialna za napisanie go.

Łukasz Kałużny: Tak i zawsze trzeba powiedzieć, czy jest to architekt czy nie. Nie, ADR-a może wprowadzać każda osoba. Czyli zwykle, nie oszukujmy się, to będzie gdzieś tam od senior developera, team leadera, architekta, to są osoby, które będą prowadziły takiego. Reviewować zwykle będzie architekt, jakiś team leader, taki technology leader takiego ADR-a.

Szymon Warda: Tak, ale to zwykle, jak powiedziałeś, to u nas jest, ten inicjalny ADR to jest po prostu pytanie, notatka generalnie, czy może byśmy o tym pomyśleli. Może być odrzucone na poziomie generalnie teraz, to nie jest w KPI-ach firmy, nie robimy tego teraz, wróćmy do tego później. Jak najbardziej. Dobrze, jeszcze z takich fajnych rzeczy to jest, czy piszemy o rzeczach oczywistych, takich, że mamy aplikację w Azure, na przykład wybraliśmy Azure Blob Storage, bo to wydaje się, że nie ma sensu pisać.

Łukasz Kałużny: Nie, bo platformowo nie ma to sensu.

Szymon Warda: Zgadzam się.

Łukasz Kałużny: Ale jeżeli powiesz, że nie wybrałem Blob Storage, tylko wybrałem co innego, to będzie warte udokumentowania.

Szymon Warda: Tak, te odejście od normalności jak najbardziej są warte dokumentacji. Zgadzam się jak najbardziej.

Łukasz Kałużny: Chyba to i takie dla mnie jeszcze kiedy? To jeżeli będziesz musiał tłumaczyć dłużej niż minutę, albo będziesz chciał użyć tłumaczenia, bo tak autorytatywnie, to oznacza, że musisz tego ADR-a napisać.

Szymon Warda: Tak. Wątpliwości wszelkie rozwianie, uporządkowanie, jak najbardziej ma sens. Dobra, podsumowując odcinek, bo trochę się dłuży nam. Twoje?

Łukasz Kałużny: Wiesz co? Po prostu warte wprowadzenia.

Szymon Warda: I to teraz, od zaraz bym powiedział nawet.

Łukasz Kałużny: Tak.

Szymon Warda: Dobrze. Z moich uwag to jest to, że pamiętajmy, że ADR-y nie są po to, żeby szukać winnych w przeszłości. To jest coś, co ktoś, kto zaczął pomysł, decyzję, to decyzja jednak jest grupowa. I to jest rozumienie decyzji i kontekstu, nie szukanie winnych.

Łukasz Kałużny: Tak. I to, co powiedziałeś bardzo ważne, pozwala nam też wskazać takie miejsca, gdzie zaciągamy dług technologiczny i potem do nich wrócić, żeby go spłacić.

Szymon Warda: Zgadza się, jak najbardziej. I w sieci, jak robiliśmy research do tego odcinka, jest dużo rozdmuchanych szablonów, takich w sensie tam jest 15 pozycji. One fajnie wyglądają,, to jest takie: to usystematyzujemy. Nie, to ma mieć dość luźną strukturę, żeby nie przerazić ludzi na wejściu.

Łukasz Kałużny: Tak, stosujemy KISS - Keep It Simple Stupid i pozwólmy z tego ludziom korzystać. Idąc za KISS-em, żadnych nowych narzędzi, repo, markdown, koniec.

Szymon Warda: Ja bym powiedział tak, zanim wybierzemy szablon wpierw w tym szablonie sami pierwszego ADR-a piszemy. Bo jak będzie: o Boże, to pole jeszcze, to wiemy, że może wybrać łatwiejszy szablon. Dobra, tyle?

Łukasz Kałużny: Tyle.

Szymon Warda: To dzięki. Na razie.

Łukasz Kałużny: Dzięki. Na razie.