Kiedy w organizacji nie ma odgórnych wytycznych odnośnie prowadzenia dokumentacji, można zbyt mocno wziąć sobie do serca Agile Manifesto, które stawia „działające oprogramowanie ponad obszerną dokumentację”. Tymczasem dobrze utrzymywana dokumentacja wnosi dużą wartość dla całego zespołu. Dokumentacja pokryje jak najwięcej obszarów, kiedy będzie tworzona przez wszystkich członków cross-funkcjonalnego zespołu. Warto, aby Product Owner czy Project Manager rozumiał wagę dokumentacji i dawał przykład w jej tworzeniu.
Dokumentację porównać można do inwestycji, która wymaga nakładu czasu, ale pozwala zaoszczędzić go nieproporcjonalnie więcej w przyszłości. Umiejętnie prowadzona dokumentacja stanowi jedyne źródło prawdy oraz wyrównuje poziom wiedzy w całym zespole.
Nie taka dokumentacja straszna, jak ją malują
Poniżej przedstawiam wybrane metody dokumentacji stosowane w moim zespole.
Słowniczek
Nauczona doświadczeniem, nigdy nie zakładam, że odbiorcy dokumentacji postrzegają produkt tak samo. Inaczej widzą system eksperci w danym procesie biznesowym, a inaczej deweloperzy, którzy więcej powiedzą o jego komponentach i architekturze. Słownik pojęć umieszczony na początku dokumentacji ma na celu zbalansowanie tej wiedzy. Dla osób technicznych interesujące będą pojęcia charakterystyczne dla danej domeny biznesowej (na przykład: czym w procesie biznesowym obsługiwanym przez system jest umowa, a czym dokument). Z myślą o przedstawicielach biznesu warto wyjaśniać techniczne kwestie (na przykład: czym jest autentykacja, a czym autoryzacja).
As-Is versus To-Be
Kiedy nowe funkcjonalności implikują dużą zmianę w istniejącym procesie, warto zacząć od udokumentowania obecnego stanu (as-is) i dopiero wtedy przejść do tworzenia stanu docelowego (to-be). Pomoże to zidentyfikować i uwidocznić odbiorcom dokumentacji wszystkie konieczne zmiany w produkcie. Skupiając się od razu na procesie to-be, możemy pominąć niektóre wymagane zmiany, co zwiększy potem koszt implementacji.
Tracker
Im więcej interesariuszy jest zaangażowanych w proces doprecyzowania wymagań, tym więcej komunikacji oraz ustaleń. Szukanie odpowiedzi w komunikacji mailowej, na czacie komunikatora lub w notatkach ze spotkań jest istną zmorą. Można jej uniknąć poprzez prowadzenie rejestru pytań w jednym miejscu dostępnym dla wszystkich. Przy pytaniu warto dodać aktualny status oraz podlinkować adresata pytania i poprosić o naniesienie odpowiedzi bezpośrednio w dokumentacji.
Tablica decyzyjna
Udokumentowanie logik może zaoszczędzić mnóstwo czasu programistów, którzy nie muszą przeczesywać kodu w poszukiwaniu „jak to właściwie działa”. W przypadku rozbudowanych logik dobrze sprawdzi się tablica decyzyjna. Pozwala ona zidentyfikować wszelkie możliwe kombinacje warunków i zaprojektować zachowanie systemu w odpowiedzi na każdą konstelację. Rysunek 1. przedstawia przykładową tablicę decyzyjną z czterema kombinacjami trzech warunków. Poniżej nich znajdują się „decyzje”, czyli działania, które zachodzą przy spełnieniu danej kombinacji warunków. Spełnione wszystkie warunki (W1, W2, W3) oznaczają, że dokument wyświetlony jest w widoku głównym dokumentów (D1), ma status „obowiązujący w przyszłości” (D3) oraz można go pobrać (D7). Jeśli warunek 1 nie jest spełniony (czyli data rozpoczęcia obowiązywania dokumentu nie jest w przyszłości, a zatem jest w przeszłości), a pozostałe dwa warunki (W2, W3) są spełnione – dokument wyświetli się w widoku głównym (D1) ze statusem „aktualnie obowiązujący” (D4) oraz będzie można go pobrać (D7). W przypadku, kiedy treść dokumentu nie jest poprawna (W3 nie jest spełniony), pozostałe dwa warunki (W1, W2) są nieistotne. W tej konstelacji dokument wyświetlony jest w archiwum (D2) oraz ma status „błędny” (D6).
Rys. 1. Tablica decyzyjna opisująca klasyfikację dokumentów do różnych statusów i widoków
Źródło: Opracowanie własneScenariusz przypadku użycia
Scenariusz przypadku użycia to nieco starszy sposób dokumentowania wymagań, który obecnie często wypierany jest przez user stories. Mimo to, warto wybrane wymagania dokumentować w ten sposób, zwłaszcza jeśli wprowadzamy nowy flow do systemu. Podobnie jak tablica decyzyjna, scenariusz przypadku użycia znacznie usprawni pisanie przypadków testowych. Tabela 1. przedstawia taki uproszczony scenariusz. Jednym z jego elementów są sytuacje wyjątkowe – miejsca, w których coś może pójść nie tak. Ich przewidzenie i przeanalizowanie pozwala na zapewnienie odpowiedniej obsługi błędów.
Tab. 1. Scenariusz przypadku użycia dla procesu akceptowania dokumentów w aplikacji przy użyciu kodu SMS
Źródło: Opracowanie własneSubiektywny dekalog dobrych praktyk
Zachęcam Czytelników do dzielenia się dobrymi praktykami w zakresie prowadzenia dokumentacji w Waszych organizacjach i uczenia się od siebie nawzajem. Przykładowo, w mojej organizacji temat dokumentacji poruszany był w ramach Community of Practice dla analityków biznesowych.
- Mniej znaczy więcej. Warto stosować pogrubienia najważniejszych pojęć oraz spis treści, nagłówki czy screeny z komentarzami.
- Unikajmy niewyjaśnionych skrótów – przynajmniej w jednym miejscu dodajmy ich rozwinięcie.
- Dokumentacja powinna być utrzymywalna. Lepiej udokumentować mniej, ale aktualizować treść na bieżąco.
- Jeśli korzystamy z różnych narzędzi, warto dodawać do nich odnośniki. Umieszczenie w przestrzeni Confluence linków do ticketów w Jirze (oraz odwrotnie) ułatwi poruszanie się między nimi.
- Dobrym sposobem dokumentowania lessons learned są różnego rodzaju instrukcje.
- Listy numerowane liczbami zamiast myślnikami czy punktami ułatwiają odbiorcom odniesienie się do danego punktu w mailu czy komentarzu.
- W przypadku implementacji nowych funkcjonalności, warto dodać w Jirze odrębne zadanie na stworzenie dokumentacji technicznej.
- W dokumentacji integracji z zewnętrznymi serwisami przydadzą się dane osób kontaktowych, do których można zwrócić się w razie awarii.
- Kiedy przesyłamy komuś linka do naszej dokumentacji, sprawdźmy najpierw, czy odbiorca ma uprawnienia do wyświetlenia strony.
- W Definition of Done zespołu można uwzględnić punkt „dokumentacja została zaktualizowana”.
Pisz listy miłosne do siebie już teraz
„Documentation is a love letter that you write to your future self”
Damian Conway
W pełni zgadzam się z autorem powyższego cytatu. Umiejętnie prowadzona i utrzymywana dokumentacja to coś dobrego, co możemy zrobić dla nas i naszych zespołów. Z pewnością przyda się w sytuacji wymagającej szybkiego działania, a wtedy będziemy mogli sami sobie za nią podziękować.
Zawodowo analityczka biznesowa w IT. Nieustannie poszerza swoją wiedzę oraz szuka nowych inspiracji. Uwielbia pracę zespołową i pozytywną energię, jaka się przy niej wyzwala. W wolnych chwilach ćwiczy fitness na stepie oraz przemierza kolejne kilometry na rowerze. Nie wyobraża sobie życia bez podróży i poznawania świata.