W czasie całego cyklu życia projektu zostaje podjęte bardzo wiele decyzji biznesowych i technicznych. Często ta wiedza nie jest usystematyzowana, zebrana w jednym miejscu i rozpowszechniana po teamie. Problem pogłębia się, gdy ludzie zaczynają odchodzić i zabierają fragmenty wiedzy ze sobą.

Wiele razy zdarzyło mi się, że pracowałem bezpośrednio z klientem nad zagmatwaną funkcjonalnością. Odbijaliśmy sobie taska, zadawaliśmy pytania, zmieniały się założenia oraz wymagania. Powstawały bugi, fixy, refactor. Po kilku takich sesjach, które czasem ciągnęły się tygodniami, nieraz sam się pogubiłem. Gdy ktoś mnie po jakimś czasie pytał “dlaczego to działa tak, a nie inaczej” to ciężko było mi wskazać jednoznaczny powód. Miałem w głowie tylko poszlaki, numery tasków i fragmenty rozmów.

Wielokrotnie brałem też udział w projektach, które ciągnęły się wiele miesięcy lub nawet kilka lat.

Pamiętam zwłaszcza ten pierwszy. Kilkuletni legacy kod, wielotysięczne klasy, olbrzymia ilość logiki biznesowej rozsiana po całym systemie i po kilkuosobowych podzespołach (również po stronie klienta), które współtworzyły różne części projektu.

Często szukałem w różnych podzespołach kogoś kto potrafi wyjaśnić mi logikę biznesową i decyzje techniczne, które muszę zrozumieć, aby dodać nową funkcjonalność lub naprawić buga.

Często nie znajdowałem tej odpowiedzi. Dla junior developera był to ciężki orzech do zgryzienia i nie pozostawało nic innego niż kodzenie na czuja. To nigdy nie jest dobre rozwiązanie.

Zagubiona wiedza techniczna potrafi również wywołać bardzo ożywione dyskusje, a tak naprawdę kłótnie. Najczęściej czara goryczy przelewa się, gdy na code review jedna osoba uzna, że coś powinno zostać zaimplementowane w dany sposób, bo “przecież zawsze tak robimy”, a druga osoba zasugeruje coś zupełnie innego kierując się swoimi “standardami jakości”, które są niezrozumiałe dla innych. Developerzy to takie stworzenia, u których kłótnie techniczne potrafią wywołać chęć pójścia po pracy za garaże żeby dać sobie w pysk.

https://media.makeameme.org/created/your-argument-1gatkf.jpg

Jeżeli przynajmniej raz w życiu doświadczyłeś choćby jednego z wymienionych wyżej problemów to może Ci się spodobać prosty sposób, dzięki któremu udało mi się je rozwiązać.

Jak odnaleźć prawdę

Wyżej wymienione problemy nie mają jednej jasno określonej przyczyny, więc nie ma złotego środka żeby je wyeliminować. Wiedza ma tendencję do gubienia się. Jest jednak sposób, który potrafi bardzo mocno zminimalizować straty wiedzy i działa na obydwa przypadki - utratę wiedzy biznesowej i technicznej.

Skąd wiem, że ten sposób działa?

Działa u moich kolegów, których opinie szanuję.

Działa u moich mentorów, którzy mi go pokazali, gdy ja jeszcze biegałem po firmowych korytarzach w pampersach.

Ale co najważniejsze - zadziałał u mnie, w każdym projekcie, w którym go stosowałem, mimo tego, że często ludzie bardzo się między sobą różnili. Poziom zadowolenia zawsze wynosił 100%.

Do rzeczy.

Prostym, szybkim i bezbolesnym rozwiązaniem jest stworzenie decision loga.

Wartość technicznego decision loga

Decision log to bardzo prosty dokument, w którym zapisywane są wszystkie ważne, podjęte w projekcie decyzje. Punkt za punktem.

Oto przykład technicznego decision loga:

1. CSS - grupujemy rule CSSowe zgodnie z zasadami określonymi przez “stylelint standard”

2. Wszystkie endpointy API powinny przyjmowac payloady z propercjami pisanymi “camelCasem” i zwracać dane z propercajmi pisane “camelCasem”. Nie powinniśmy używać “UPPER_CASE’a” ponieważ wprowadza dodatkową warstwę mapowania w UI i kompliuje kod. Tylko dane zapisane “camelCasem” zgadzają się z naszą konfiguracją statycznej analizy kodu, poza tym ciężej jest używać tego samego kodu w różnych miejsach, gdy jest on zapisany “UPPER_CASEm”

3. Query SQLowe nie powinny być hardkodzone w plikach js. Aby utrzymać porządek wszystkie powinny znajdywać się w folderze “sql”, w głównym katalogu projektu.

Jak widzisz, jest to niesamowicie prosta struktura informacji, a dostarczyła wiele wartości w projektach, w których brałem udział.

Gdy ktoś wystawiał na code review kod niezgodny z naszymi ustaleniami, wystarczyło podesłać mu numery decyzji z decision loga żeby wiedział co poprawić, no hard feelings.

Ludzie przestali kłócić się o mało ważne szczegóły związane z ich osobistymi przekonaniami np. spacje vs taby, 4 spacje czy 2 spacje, jak formatować ify, jak duże mogą być CR-ki, itp.

Kod wyglądał podobnie mimo tego, że pisało go wiele osób i tym samym łatwiej było go zrozumieć. Czuliśmy, że kod jest bardziej wspólny.

Wprowadziliśmy jasne standardy odnośnie performance’u i security.

Wiedzieliśmy dlaczego, w niektórych miejscach kod nie jest napisany idealnie i że odzwierciedla to świadomą decyzję podjętą w przeszłości.

Przestaliśmy, w kółko dyskutować o tym samym. Nie od dzisiaj wiadomo, że mózg podczas podejmowania decyzji, zwłaszcza tych trudnych, zużywa dużo energii, w momencie, gdy decyzje są już podjęte możemy tę energię przeznaczyć na coś bardziej pożytecznego.

[caption id=“attachment_324” align=“aligncenter” width=“600”] https://i.imgflip.com/14z9ok.jpg[/caption]

Wartość biznesowego decision loga

Decision log z decyzjami biznesowymi buduje się dokładnie w taki sam sposób. Zawiera on jednak decyzje na wyższym poziomie.

Przykład:

1. Zmiana daty jest globalna. Oznacza to, że każda zmiana daty powoduje ponowne pobranie danych wszystkich firm w całej aplikacji. Gdy data nie jest wybrana, powinniśmy domyślnie ustawić ją na dzisiejszy dzień. Nigdy nie powinno być sytuacji, że wykonujemy zapytanie do API bez ustawionej daty. [2018-02-01, daily meeting z klientem]

2. Wyjątek od powyższej reguły - na niektórych podstronach, mimo wybranej daty, powinniśmy wysyłać do API dzisiejszą datę [2018-02-01, daily meeting z klientem]

3. CSSy powinny być łatwo wymienialne w zależności od tego na jakiego użytkownika jesteśmy zalogowani, przy wybieraniu sposobu zarządzania plikami CSS powinniśmy odrzucić wszystkie techniczne opcje, które nie wspierają tego wymagania, a preferować te, które nam to ułatwią [2018-02-04, zmiany do specyfikacji, link]

W małych projektach decyzje biznesowe przechowywane są czasem razem z technicznymi i nie ma w tym nic złego dopóki nie powoduje to bałaganu. Ja zawsze proponuję zrobić z niego osobny dokument, gdy liczba biznesowych decyzji jest większa niż 3 (The Rule of Three Twoim przyjacielem).

Za każdym razem, gdy wspólnie z klientem podejmiesz ważną decyzję zapisz ją w decision logu.

W jednym z moich projektów pewna decyzja klienta odnośnie działania kluczowej funkcji systemu doprowadziła do tego, że byliśmy w stanie wyeliminować problematyczne warunki brzegowe w tym jak pobierane były dane z serwera. W rezultacie uprościł nam się kod i zredukowaliśmy czas potrzebny na implementowanie nowych funkcji w aplikacji. Jest to wartość dla biznesu i dla programistów. Wszyscy byli zadowoleni.

Gdy do decision loga, poza datą, dodamy dokument, fragment rozmowy lub jakiekolwiek inne źródło konkretnej decyzji, a także okoliczności jej podjęcia to może on służyć jako bardzo dobre “zabezpieczenie” przed wątpliwościami klienta.

Potrzeba tworzenia “zabezpieczeń” często świadczy o tym, że nie najlepiej rzeczy się mają w tym naszym projekcie, jednak może się przydać, gdy nie mamy wyboru.

Znacznie częściej zdarza się jednak, że zabiegany klient, który miał wiele spraw na głowie po prostu zapomniał, że podjął już jakąś decyzję. Klienci to też ludzie i tak jak my mogą o niektórych rzeczach zapomnieć i wtedy naszą odpowiedzialnością jest im przypomnieć.

W takich sytuacjach zapis w decision logu z konkretna datą i informacją w jakich okolicznościach ta decyzja zapadła (np. na grudniowym callu na Skypie) jest najszybszą metodą odświeżenia pamięci. Pomoże to uniknąć niepotrzebnych konfliktów, których w tym przypadku nie będzie dało się rozwiązać szybką bójką ;).

Dodatkowo, taki zapis może służyć przyszłym dyskusjom między Tobą a klientem jeśli chcielibyście zweryfikować czy podjęta dyskusja była słuszna i ewentualnie ją zmienić. Stawia Cię to również w dobrym świetle - profesjonalisty, któremu zależy i który potrafi przedstawić sensowne argumenty.

Znacznie lepiej pracuje się na konkretnych, spisanych przykładach niż na wątłych obrazach w pamięci.

[caption id=“attachment_325” align=“aligncenter” width=“300”] https://www.joyofdance.ca/wp-content/uploads/2018/04/memory-meme-300x225.jpg[/caption]

Jak tworzyć dobre decision logi

Decision log jest dokumentem bardzo prostym, mam jednak kilka rad, które uczynią go jeszcze przydatniejszym.

Dodaj kontekst

Na powyższych przykładach niektóre punkty decision loga są oczywiste. Są po prostu są jedną z możliwych opcji, które wybrał zespół lub klient np. formatujemy CSS w taki sposób, bo w jakiś trzeba i tyle.

Inne wymagają wyjaśnienia. Jeśli decyzja nie jest oczywista to warto nakreślić kontekst. Dodaj punkt do decision loga i odpowiedz na pytanie “dlaczego?”. Gdy tego nie zrobisz, ktoś z projektu przyjdzie do Ciebie po kilku miesiącach i zada to pytanie. Ty wtedy możesz już nie pamiętać i decyzja będzie bezużyteczna.

Dodaj datę i okoliczności

Jak już wspomniałem, czasem warto dodać datę do każdego punktu. Może się ona przydać, gdy projekt jest szczególnie burzliwy i często zmieniają się wymagania.

Może się wtedy okazać, że jakaś decyzja przestaje mieć sens i nie możemy się do niej odwoływać.

Np. pochodzi z czasów, gdy używaliśmy jeszcze starej wersji biblioteki. Lub została podjęta we wczesnych etapach projektu, gdy jeszcze nie posiadaliśmy wystarczającej wiedzy żeby zadecydować, że dany punkt jest bez sensu (a jakąś decyzję trzeba było podjąć).

Automatyzuj

W przypadku takich rzeczy jak formatowanie kodu warto wymusić standardy poprzez zastosowanie plików konfiguracyjnych do edytora i statycznej analizy kodu. Są to wszelkiego rodzaju lintery i editorconfigi.

Zmniejszy to ilość komentarzy na CR-ce.

Twórz dokumenty zgodnie z dobrymi praktykami

Decision log powinien być zgodny z dobrymi praktykami tworzenia dokumentów. Czyli:

- dostępny dla każdego, zawsze i wszędzie, najlepiej stosować rozwiązania typu Google Docs, czyli takie, z których można korzystać z każdego urządzenia i z każdego miejsca na ziemi - powinieneś przechowywać go w miejscu, które posiada dobrą wyszukiwarkę, czasem może nazbierać się nam decyzji i wtedy nie ma nic lepszego niż wyszukiwarka - zcentralizowany - oznacza to, że powinna istnieć tylko jedna kopia dokumentu (+ ew. kopia zapasowa), jedno źródło prawdy, tak żeby każdy powoływał się zawsze na jeden i ten sam dokument, wyeliminuje to niejasności

Wrzuć do repozytorium

Wiele firm i konsultantów wychodzi ze słusznego założenia, że wszystkie artefakty związane z tworzeniem projektu należą do klienta. Decision log również.

Z doświadczenia wiem, że często zespół developerski korzysta ze swoich narzędzi odnośnie przechowywania dokumentów, a klient ze swoich. Dokumenty wymieniane są mailami lub wrzucając pliki na chmurę. Stosując te sposoby bardzo ciężko o wersjonowanie i spójność.

W takim wypadku warto zastosować prostą sztuczkę i wrzucić decision log do repozytorium jako plik markdown.

Nikt nie będzie bardziej szczęśliwy niż developerzy, którzy będą mogli zacommitować decyzję w repozytorium. Będzie można poddać ją code review, więc wyeliminuje to problem tego, że ktoś o decyzji nie wiedział, albo nie mógł się wypowiedzieć. Każde repozytorium ma również wyszukiwarkę, która bardzo dobrze radzi sobie z plikami tekstowymi.

Największą zaletą będzie jednak to, że dokument będzie dostępny dla klienta - od razu, jeśli kod jest na jego serwerach lub ma do niego dostęp, lub podczas przekazania kodu.

Bonus tip - przechowywanie dokumentów w repozytorium działa również w przypadku dokumentacji, która jest wtedy cały czas dostępna i nie trzeba przeszukiwać zewnętrznych systemów, aby cokolwiek znaleźć. Jest duża szansa, że dokumentację już przechowujesz w taki sposób, więc powinieneś dostrzegać zalety.

Poinformuj każdego o decyzji

Najważniejszy punkt. Gdy dodajesz decyzję do decision loga musisz ją jasno wszystkim zakomunikować. Najlepiej, aby każda nietrywialna decyzja podejmowana w zespole została poddana głosowaniu, o którym będą wiedzieć wszyscy zespole. Nawet jeśli w czasie podejmowania decyzji byli na urlopie w Bieszczadach i odcięli się od świata. Nikt nie może czuć się pominięty.

Miałem kiedyś nieprzyjemną sytuację, ponieważ jeden z członków zespołu nie był świadom tego, że podjęliśmy kilka decyzji, w czasie gdy był nieobecny.

Był wówczas kimś na kształt lidera zespołu. Narzędzie, którego używaliśmy do decision loga jasno wskazywało, że autorem wpisów, których istnienia nie był świadom, jestem ja. Uznał więc, że podjąłem te decyzje samowolnie. Wyładował swoje frustracje oskarżając mnie o bycie zespołową wyrocznią do podejmowania decyzji.

Wina oczywiście stała po mojej stronie, ponieważ nie zakomunikowałem wystarczająco jasno, skąd wzięła się dana decyzja i że cała reszta zespołu doskonale o niej wie. Nie przestrzegałem zasady, którą właśnie czytasz.

Podsumowanie

W ostatecznym rozrachunku, to komunikacja jest kluczowym aspektem w procesie wytwarzania oprogramowania. Im bardziej ułatwimy wymianę i przechowywanie wiedzy, tym mniej damy sobie okazji do błędów komunikacyjnych. Decision log jest jednym z narzędzi, które bardzo pomagają.

Gdy dobrze go zorganizujesz to pomoże Ci uniknąć nieporozumień, ujednolicić wiedzę na temat różnych aspektów projektu i będzie stanowić dobrą podstawę do dyskusji z klientem.

Daj znać jeśli znasz dodatkowe sposoby na poprawę komunikacji. Chętnie zastosuję u siebie.