Fajnie, że jesteś
Mam nadzieję, że poniższy artykuł przypadnie Ci do gustu. Nie przywiązuj zbyt dużej wagi do daty powstania tego wpisu. Nawet jeśli napisałem go na początku istnienia bloga, to staram się przynajmniej raz w roku przeglądać stare treści i je aktualizować. Jeżeli mimo wszystko zauważysz jakąś nieścisłość w tekście, to daj mi proszę znać w komentarzu poniżej.
Pamiętaj także, że wartość tego bloga podbijają pozostawione tu komentarze. Jeżeli temat poruszany we wpisie Cię interesuje, to polecam doczytać także komentarze do niego. Znajdziesz w nich chociażby punkt widzenia innych osób, czy dodatkowe informacje, o których ja zapomniałem lub nie wiedziałem.
4 sierpnia 2021 at 14:18
Niezależna komisja wybrała zwycięzców. Oto oni:
– Borys
– Marek Siwiec
– kuba86
– Ewa B.
– Krzysztof
W sprawie przekazania nagród skontaktuję się z każdym mailowo. W przypadku braku odpowiedzi nagroda przechodzi na szczęśliwców z ławki rezerwowych.
25 lipca 2021 at 04:58
Kiedy nasza organizacja podejmuje decyzje architektoniczne, postępujemy z tymi zasadami:
• Chcesz uniknąć podejmowania decyzji i nie powiedzieć, DLACZEGO je zrobiłeś. Na przykład – pewna decyzja dokonana tymczasowo może wydawać się dużą stałą decyzją dla kogoś, kto właśnie dołączył do zespołu, ale w rzeczywistości nie są
• Nagraj decyzję na 1-2 stronach, jeden plik na decyzję, przechowywany w git repository (wraz z source kodem), markdown/asciidoc format
• Ten rekord jest niezmienny, ale może być zastąpiony
• ARCHITECTURE DECISION RECORD (ADR):
# Title
## Status – proponowany/akceptowany/zastąpiony
## Context – zwykle zebrany w grupie
## Decision – architekci powinni być osadzone z deweloperami, więc decyzja jest podjęta organicznie i nie wręczając im
## Consequences
• Unikaj diagramów, kontekst jest ważniejszy
• Nowe zachowania/wzory będą używane teraz, muszą być przechwycone tutaj (ADR)
• Blade są centralne, architektonicznie znaczące decyzje są trudne do zmiany w przyszłości (np. zamknij niektóre drzwi), to jest organizacja specyficzna i kontekstualizowana
• Używaj tools, takich jak „Antora”, aby opublikować decyzje w jednym miejscu jako miejsce statyczne z wyszukiwaniem
13 lipca 2021 at 22:49
Wszystkie takie decyzje staram się trzymać jak najbliżej kodu. A wiadomo, że najbliżej kodu są programiści – także trzymamy je w ich głowach. Do tego rozwiązanie jest wersjonowane, bo często mają różne wersje tego samego ustalenia!
A, jest jeszcze Confluence, „konflu” jest najważniejsze, no i maile pupochrony! Ale tam nie ma całej prawdy…
13 lipca 2021 at 08:02
Slack w płatnym pakiecie aby można było więcej scrollować i przeszukiwać 🙂
11 lipca 2021 at 09:20
Jako, że jesteśmy małym zespołem dlatego wybraliśmy rozwiązaniem open-source self-hosted kanboard. Ma bardzo dużo fajnych rozwiązań począwszy od zdefiniowania automatycznych czynności np. przy przeniesieniu taska do innej kolumny automatycznie zmienia się np. jego status. Bardzo przydatne rzeczy. Kolejna przydatna funkcja, przynajmniej u nas, jest wyszukiwarka z możliwością stosowaniu filtrów np. Project:”test” status:”open”. Funkcja na bieżąco wykorzystana u nas 🙂
Pozdrawiam
9 lipca 2021 at 17:11
Za każdą dużą zmianą stoi design doc (GoogleDoc) który zawiera informację co i dlaczego się zmienia. Czasem powstają również dokumenty z porównaniem różnych opcji i podsumowaniem dlaczego akurat tak.
Trzymanie takiego dokumentu nie w repozytorium ma tą zaletę, że dużo łatwiej jest komentować/edytować google docs niż pull request. Prawdopodobnie kiedyś dojdziemy do tego, że te dokumenty wylądują w repo ale wtedy stracimy dostęp do komentarzy z google docs.
Mniejsze zmiany dokumentuje się w opisie pull requesta. Niestety z nieznanych mi powodów nie utrzymujemy tego w commit description 🙁
9 lipca 2021 at 12:31
W projekcie w którym pracuję korzystamy z Frameworka ADR (https://github.com/joelparkerhenderson/architecture-decision-record) Tak na serio miejsce przechowywania nie ma znaczenia, ważniejsze jest, by:
1) Wszyscy mieli dostęp do historii podjętych decyzji
2) Wszyscy rozumieli dlaczego zapadła konkretna decyzja
3) Dokumentacja była wyznacznikiem dla nowych członków zespołu jak rozumieć i kontynuować przyjętą konwencję
4) Dokumentacja była Single Source of Truth – eliminując rozproszenie wiadomości po członkach zespołu
To chyba tyle 🙂 Co do samego miejsca przechowania – Github (repo ADR), Confluence (wiki)
1 lipca 2021 at 14:11
Azure DevOps, strony wiki. Proste w użyciu, dostępne dla wszystkich w organizacji, historia zmian. 🙂 Oczywiście PM na początku się bronił że „Word lepszy” ale kto bym tam słuchał takich opinii. Architectural Decision Page został utworzony, prosty szablon w Markdown stworzony i w niecałe 10 min JOB DONE!
Zasada „rule of least power” zawsze się sprawdza.
Dla zainteresowanych info o Architectural Decision Records: https://adr.github.io/ naprawdę warte przeczytania!
29 czerwca 2021 at 16:09
Część decyzji przechowywanych jest w ramach ticketów na JIRA czy pull requestach. To wychodzi samo z siebie, podczas dyskusji lub podsumowań. Jeśli jednak są to ważniejsze decyzje to w plikach md w ramach repozytorium, czyli ADRki.
Oczywiście też w wewnętrznej dokumentacji(uml i tekst) na Hugo, ale wiecie jak to jest z dokumentacją. ADR rządzą.
28 czerwca 2021 at 00:43
Nie ma dokumentacji – wiedza jest w ludziach.
Jak ludzie odejdą to zostają diagramy C4 oraz ADR/ADL (architecture decision record oraz architecture decision log)
27 czerwca 2021 at 08:33
Większość decyzji musi być skonsultowana z klientem. Do dziś nie odkryliśmy lepszego narzędzia niż porządnie napisane meeting minutes… W mailu 🙂
Odpowiedni temat, struktura, dobry project manager – brzmi archaicznie ale działa.
Mocno rozważamy jednak wykorzystanie do tego celu slacka!
25 czerwca 2021 at 10:30
W pracy nie ma wielkiego wyboru – korzystam z tego, co oferuje projekt/pracodawca albo z czego korzysta zespół. Zwykle jest to Confluence, który z większością zadań jakoś sobie radzi, no i przyjeżdża w pakiecie z resztą Atlassianowego zespołu narzędzi. Ma swoje uciążliwości, ale da się z nimi żyć. A w zespole liczy się przede wszystkim standaryzacja i ludzkie przyzwyczajenia.
Prywatnie jestem fanem Evernote, który przede wszystkim służy do robienia notatek, ale w zasadzie jest uniwersalnym kombajnem do przetwarzania i porządkowania większości informacji, od brainstormingu do budowania hierarchicznej dokumentacji. Fakt, trochę gorzej radzi sobie w zespołach (nie oferuje współbieżnej edycji), ale do pracy samodzielnej wymagającej skupienia i łatwości wyszukiwania wcześniejszych notatek – jak znalazł!
25 czerwca 2021 at 08:53
Wszelkie decyzje projektowe przetrzymywane są w postaci ADRów na Confluencie. Mamy szablon wg którego powininniśmy opisać kontekst problemu, możliwe rozwiązania i podjętą decyzję z uzasadnieniem. Oprócz opisu mile widziane są UML, najczęściej pisane w PlantUML.
Natomiast decyzję tyczące się stricte poszczególnych serwisów trzymane są w repozytorium razem z kodem. W każdym repozytorium znajduję się katalog adrs, w których trzymamy ADRy w formacie .md.
25 czerwca 2021 at 08:39
Confluence ponieważ idealnie integruje się z Jira. 🙂
25 czerwca 2021 at 08:33
Do przechowywania decyzji używamy Azure DevOps.
Prostsze decyzje podejmowane na refinementach wpisywane są bezpośrednio do powiązanych User Stories.
Te bardziej ogólne i ważniejsze spisywane są na stronce wiki, w formie ADR’a.
25 czerwca 2021 at 08:08
Hej.
Małe decyzje podejmujemy na daily i zapisujemy to do Jira w odpowiednich zadaniach. Bardziej złożone i ważne są zapisywane w ADR-ach i trzymane razem z kodem projektu. Żeby było też bardziej dla wzrokowców, to sporą część flow zawierają diagramy UML robione w PlantUML. I znowu, da się to trzymać w repo jako tekst 🙂 Ostatnio nasz system zaczyna rosnąć i pączkować o mikroserwisy, więc rozważamy, by model C4 pomógł nam zaprezentować, czy nasze ustalenia mają sens i szansę na działanie.
25 czerwca 2021 at 01:00
Zainteresowany ebookiem proszę!
Najpierw analizujemy wszystkie nasze zależności serwisowe.
Następnie nasz zespół uzgadnia „design template”, podobny do tego:
https://docs.google.com/document/d/1dyIxdsC7CeDvAe28RybV50RXaybfJ550f9n6VVmMrUQ
Nasz scrum master przenosi elementy na Kanban board w różnych kolorach. Następnie przenosimy elementy między „to do”, „in progress” i „done”.
24 czerwca 2021 at 22:37
Wszelkie decyzje oraz kontekst trzymam najbliżej kodu jak tylko się da – czyli razem z nim i korzystając ze wsparcia systemu kontroli wersji 🙂