Minimum dokumentacji w zespole produktowym
W dzisiejszym artykule poruszamy temat, który przeraża wiele zespołów. Dokumentacja 👻.
Opowiemy o tym, w jaki sposób tworzyć jej niezbędne minimum, które przynosi wartość i nie dodaje zbyt dużo komplikacji. Powiemy co można, co trzeba, a co warto dokumentować.
Minimum dokumentacji w zespole
Rozmowę o dokumentacji warto rozpocząć od wymienienia powodów, przez które zwykle nie dokumentujemy.
Dlaczego nie dokumentujemy
Poniżej znajdziesz garść powodów, które zebrałem w ramach mojej pracy z różnymi firmami i to, co zasugerowałem im w odpowiedzi:
„Dokumentacja staje się przestarzała niemal natychmiast po jej napisaniu.
Dokumentujesz ręcznie to, co powinno być zaktualizowane automatycznie.
„Dokumentacja zajmuje czas, który może być poświęcony na tworzenie produktu".
Tak tylko się wydaje, brak podstawowej dokumentacji sprawia, że pracujesz jeszcze wolniej.
Mój kod jest samodokumentujący
Kod odpowiada na pytanie, CO jest napisane, ale nie DLACZEGO jest tak napisane.
„Za dokumentację nikt nie jest odpowiedzialny."
Dokumentacja musi być zintegrowana z praktykami zespołu, by zespół jako całość brał odpowiedzialność.
Dokumentacja nie przyczynia się bezpośrednio do zwiększenia wartości produktu.
Dokumentacja zwiększa pośrednio wartość produktu, przez ułatwienie jego rozwoju i utrzymania.
Moim głównym spostrzeżeniem dotyczącym dokumentacji jest to, że nie potrafimy optymalnie wybrać tego, co chcemy dokumentować. Jeśli już zaczynamy to robić, to wchodzimy od razu na 100%, próbując dokumentować absolutnie wszystko. W efekcie tracimy czas, który nie przekłada się na zyski. I ostatecznie, zawiedzeni, ubijamy całą inicjatywę.
Więc jak dokumentować, aby zmaksymalizować zyski?
By to zrozumieć, trzeba się najpierw zastanowić co w ogóle można dokumentować.
Co można dokumentować
Na potrzeby szkolenia Engineering Manager zebrałem w jedną listę informacje o tym, co w zasadzie można gromadzić i dokumentować w ramach produktu. Zebrało się tego ponad 25 pozycji. 🤯
Produkt
Skupiamy się na samym produkcie cyfrowym:
Informacje o otoczeniu biznesowym
Cele i strategia produktu
Zależności
Dług produktu (techniczny, procesowy, UX)
Interesariusze
Wykorzystywanie produktu
Finanse, jak zarabiamy
Praca
Tutaj patrzymy na informacje dookoła zarządzania pracą:
Plany
Zadania
Procesy pracy
Postęp prac
Onboarding
Struktura organizacyjna
System
Produkt to jedno, ale technikalia to już inne zagadnienie:
Gdzie coś jest, jak się tam dostać
Parametry komunikacji systemowej: adresacja, kontakty
Architektura systemu
Przypadki użycia
Informacje “niebezpieczne” - klucze, hasła
Systemy zewnętrzne
Zasoby infrastrukturalne
Proces wdrażania na produkcję
Ludzie
Produkty tworzą ludzie i tutaj też mamy wiele informacji do gromadzenia:
Kto pracuje w danym zespole
Rola, odpowiedzialności
Umiejętności i upskill
Feedback od/do pracowników
Budżety, wynagrodzenia
Zadowolenie z pracy
Sporo tego, prawda? 🤔
Aby sobie poradzić z tym natłokiem, można wykorzystać dodatkowe wymiary oceny dokumentacji.
Wymiary dokumentacji
Pierwszym sposobem, w jaki możemy patrzeć na daną kategorię informacji, jest to, jak często te informacje się zmieniają.
Osobiście uważam, że warto rozpocząć od dokumentowania tego, co ma niskie tempo zmian. Aspekty po prawej stronie powyższego spektrum warto automatyzować. Inaczej ryzykujemy dużo pracy nadmiarowej nad samym utrzymaniem dokumentacji…
W kolejnym kroku możemy się zastanowić nad interesariuszami tej dokumentacji i nanieść ich na macierz wykorzystania informacji. Poniżej taki przykład dla „Postępu prac w zespole".
Według mnie warto dokumentować to, co:
Ma możliwie szeroką grupę interesariuszy
Ich potrzeby szczegółowości są podobne.
Pod uwagę trzeba jeszcze brać bezpieczeństwo danych. Nie wszystkie informacje mogą być ogólnodostępne. Przykładowo, klucze do produkcji wygodniej byłoby trzymać w łatwo dostępnym miejscu. Ale jeśli tego celowo nie robimy – jest trudniej, ale to konieczne.
Co warto dokumentować
Poniżej wybrałem aspekty warte dokumentowania, wraz z krótkim komentarzem, jaką wartość daje poszczególna dokumentacja.
Całość w skrócie pokazałem na mojej tablicy Miro. Oczywiście możecie to robić we własnych Confluence’ach, Jirach czy innych narzędziach, jakie posiadacie.
Pamiętajcie, że lepiej mieć coś w nawet ograniczonym narzędziu, niż nic, czekając na najlepsze narzędzie 😉
Cel i otoczenie biznesowe produktu
Analogicznie do Simona Sinka, rozpoczynamy od DLACZEGO – chcemy rozumieć w jakich uwarunkowaniach powstaje produkt.
Cel biznesowy - Po co dostarczamy to, co dostarczamy
Pozwala lepiej dobierać rozwiązania, daje motywację i kierunek działania.Definicje – Co oznaczają skróty, nietypowe określenia
Zwiększają zrozumienie tego co się dzieje w produkcie.Interesariusze - Klienci zewnętrzni, wewnętrzni, inwestorzy czy zespoły deweloperskie
Rozumiemy od kogo zależymy / kto od nas zależy + mamy do nich kontakt.
Zespół
Bawią mnie sytuacje, w których trafiam do większej organizacji / kilkuzespołowego produktu i nie ma takich podstawowych informacji. Efekt? Ludzie randomowo łapią się na Slacku, stalkując się wzajemnie, aby się czegokolwiek dowiedzieć. A przecież koszt zarządzania tymi informacjami jest prawie zerowy.
Skład zespołu – Kim są poszczególne osoby, jakie mają umiejętności
Pomaga w szybkim zorientowaniu się w uczestnikach danego zespołu.Role i odpowiedzialności – Kto jest liderem, jakie są role zespołowe
Unikamy ping-ponga pomiędzy różnymi osobami.Reguły pracy – W jakich godzinach działamy, jak się komunikować
Ułatwia komunikację wewnątrz / zewnątrz zespołu.
System
Jak często zmienia się wam adresacja systemu? Zdarza się, że szukacie tego jednego linka, aby wbić się na środowisko UAT? No właśnie. Podstawowe informacje o systemie warto mieć zgromadzone w jednym, wyznaczonym miejscu, by przyśpieszać sobie pracę.
Dostęp do systemu – Gdzie stoją usługi produkcyjne, testowe, jak uzyskać do nich dostęp
Kluczowe dla nowych członków zespołu oraz w sytuacjach awaryjnych, gdy pamięć zawiedzie.Zależności i integracje – Jakie są systemy zewnętrzne, od czego zależymy technicznie
Przyśpiesza zrozumienie ekosystemu, w którym działa produkt.Model C4 – Wizualizacja bazowej architektury systemu
Pomaga zespołowi produktowemu i interesariuszom w planowaniu pracy i dyskusjach pomiędzy zespołami.ADR – Decyzje architektoniczne podejmowane przez zespół
W dłuższej perspektywie buduje zrozumienie, dlaczego wybrano daną opcję architektoniczną.
Główne scenariusze użycia
Jeśli chcesz szybko przekazać HOW produktu, to jak to zrobisz? Celowo nie wchodzimy tu w szczegóły – jak kogoś zainteresuje to sobie poszuka.
Kluczowe procesy biznesowe – 3 najważniejsze scenariusze użycia
Chcemy rozumieć, co robi produkt w maksymalnie 3 zdaniach.Wymagane role – Kto ma jakie prawa w systemie
By rozumieć podstawowe kwestie autoryzacyjne dookoła przypadków użycia.Metryki produktowe – Co i gdzie mierzymy w ramach produktu
Jak monitorujemy i oceniamy, czy produkt działa prawidłowo.
Proces wdrażania
Proces wdrażania jest zwykle ustrukturyzowany. Dlaczego? Ponieważ w dzisiejszych czasach CI/CD jest prawie niemożliwe dostarczanie efektywnie bez stabilnego procesu. A to znaczy, że można to pokrótce opisać tak, by było jasne dla zespołu i interesariuszy.
Proces CI/CD – Opis kroków i narzędzi używanych przy wdrażaniu
YAML nie jest na tyle zrozumiały, by pokazać wysokopoziomowo co i dlaczego to robimy.Środowiska – Spis wszystkiego, przez co przechodzi nasza paczka wdrożeniowa
Z innej perspektywy niż wyżej, bo tutaj opisujemy, dlaczego te środowiska w ogóle są i do czego służą.Procedury awaryjne i rollback - Instrukcje dotyczące postępowania w przypadku nieudanego wdrożenia
Zmniejszają czas reakcji i ogranicza potencjalne szkody.
Praktyki dookoła dokumentacji
Czy wdrożenie tego, co powyżej wystarczy? Tak łatwo niestety nie ma. Plan weźmie w łeb, jeśli nie zbudujecie sobie dobrych praktyk dookoła dokumentacji. Jeśli nikt nigdy tego nie aktualizuje, to stopniowo, ale nieubłaganie posunie się to w stronę niebytu.
Z drugiej strony, jeśli startujemy z poziomu 0, to naszym pierwszym zadaniem jest zebranie tych informacji. Niby nie jest to tak dużo, ale na początku może jednak przytłoczyć. Warto więc rozpocząć od tego, czego w danym momencie zabrakło. I krok po kroku stworzyć dokumentację, zaczynając od najbardziej palących braków.
Następnie - aktualizacja. Celowo wskazałem powyżej informacje, które zmieniają się rzadko, by ich aktualizacja nie była dużym problemem. Jednak pomimo tego je wszystkie trzeba aktualizować.
Praktyką, od której zaczniemy, może być na przykład umieszczenie aktualizacji części informacji w Definition of Done. To może być np. aktualizacja modelu C4 po zmianach architektury. W ramach planningu czy refinementu można też analizować, jaka część dokumentacji będzie wymagała zmiany. Wtedy po wprowadzeniu danej zmiany, przenosimy ją od razu do dokumentacji.
Warto wyrobić sobie nawyk pytania, przykładowo na daily, czy retrospektywie, jakie informacje zmieniły się w ciągu ostatniego spotkania. Jeśli coś jest inne, to od razu to aktualizujemy (nie dodawajcie tylko miliona ticketów w Jirze 😅).
Kluczowe jest również to, by każdy członek zespołu mógł te informacje zmieniać. Musimy dać zespołowi jak największą władzę nad zmienianiem dokumentacji. W przeciwnym razie dochodzimy do sytuacji wąskiego gardła w postaci jednego jedynego Engineering Managera, który może zmieniać informacje. Co, jeśli pójdzie na urlop albo L4? 😉
Wartościową praktyką jest również dopisywanie (w formie komentarzy / wpisów poniżej), jakiej informacji zabrakło. Wtedy kolejna osoba, która wchodzi i akurat wie, może dodać brakujący element.
Podsumowanie
Mam nadzieję, że udało mi się przekonać Cię, że dokumentacja nie gryzie, a ten artykuł pomoże Ci rozpocząć pracę z obiegiem informacji w twoim zespole. Pamiętaj, że nie chodzi o to, by poświęcać bardzo dużo czasu, ale dostarczać realną wartość.
Dokumentacja jakaś musi być, niekoniecznie duża, da radę też minimalna. 😀
Jakich praktyk Twoim zdaniem tutaj zabrakło? Daj znać w odpowiedzi!