Minimum dokumentacji w zespole produktowym2023-11-05Cześć! W dzisiejszym wydaniu dwutygodnika 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ć. A więc w dzisiaj mam dla Ciebie: Miłego czytania 😀 Inżynierska prasówkaW dzisiejszym newsletterze przygotowałem dla was następujące 5 materiałów do zgłębienia:
Minimum dokumentacji w zespoleRozmowę o dokumentacji warto rozpocząć od wymienienia powodów, przez które zwykle nie dokumentujemy. Dlaczego nie dokumentujemyPoniż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:
Dokumentujesz ręcznie to, co powinno być zaktualizowane automatycznie.
Tak tylko się wydaje, brak podstawowej dokumentacji sprawia, że pracujesz jeszcze wolniej.
Kod odpowiada na pytanie, CO jest napisane, ale nie DLACZEGO jest tak napisane.
Dokumentacja musi być zintegrowana z praktykami zespołu, by zespół jako całość brał odpowiedzialność.
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
Praca
System
Ludzie
Sporo tego, prawda? 🤔 Aby sobie poradzić z tym natłokiem, można wykorzystać dodatkowe wymiary oceny dokumentacji. Wymiary dokumentacjiPierwszym 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:
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 produktuAnalogicznie do Simona Sinka, rozpoczynamy od DLACZEGO – chcemy rozumieć w jakich uwarunkowaniach powstaje produkt.
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.
SystemJak 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ę.
Główne scenariusze użyciaJeśli chcesz szybko przekazać HOW produktu, to jak to zrobisz? Celowo nie wchodzimy tu w szczegóły – jak kogoś zainteresuje to sobie poszuka.
Proces wdrażaniaProces 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.
Praktyki dookoła dokumentacjiCzy 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. PodsumowanieMam 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 na maila! 📧 Prześlij dalejDzięki, że doczytałeś(aś) do końca. 😊 Wszystkie poprzednie wydania newslettera są dostępne tutaj. Jeśli spodobał Ci się mój newsletter, prześlij go proszę osobom, którym też mógłby się spodobać. Z góry dziękuję. A jeśli nie jesteś jeszcze w newsletterze, to zachęcam do zapisania się. Polecam się na przyszłość!  "Inżynierskie podejście do produktów cyfrowych." P.S. Co myślisz o tym newsletterze? Odpisz :) |
