Projekty z zakresu szeroko pojętej architektury posiadają bardzo obszerną dokumentację. Zasadniczo można dojść do wniosku, że produktem przy tych projektach w istocie jest dokumentacja: dziesiątki opisów, rysunków, kart technicznych, specyfikacji, tabel i uzgodnień i najlepiej w 5 lub 6 egzemplarzach.
Miałam okazję pracować przy projekcie, którego dokumentacja techniczna, po wydrukowaniu, zajmowała cały bagażnik samochodu typu kombi. I całe jego tylne siedzenie. I jeszcze kolana pasażera. Ilość papieru zużytego do wydrukowania tej dokumentacji przestaliśmy liczyć w ryzach papieru, a zaczęliśmy liczyć w kilometrach. Ten konkretny projekt nie był odosobnionym przypadkiem, jeśli chodzi o obszerność dokumentacji. Przy projektach architektonicznych dokumentacja techniczna jest wielotomowa, rozległa i szczegółowa. Dlaczego? Ujmijmy to tak: ze względu na deployment. Jest zawsze tylko jeden. Zawsze od razu na środowisko produkcyjne. Ponieważ beton leje się tylko jeden raz. Jeśli się pomylisz, wydarzą się na pewno dwie rzeczy – ktoś straci dużo pieniędzy, a ktoś inny straci pracę. Zazwyczaj jedną z osób jest projektant. Przy odrobinie szczęścia przytrafi mu się tylko jedna ze wspomnianych rzeczy.
Praca dewelopera oprogramowania nie różni się bardzo od pracy projektanta. Inne są klocki, z których budują oni swoje rozwiązania, inny nacisk jest kładziony na poszczególne elementy pracy, ale problemy są bardzo podobne. Podobnie jak efekt końcowy – ma „działać”. Tworzenie oprogramowania jest jednak procesem dużo bardziej elastycznym niż budowa obiektów architektonicznych.
Zapytaj deweloperów, jakie czynności są przez nich najmniej lubiane. Konieczność pisania dokumentacji na pewno znajdzie się wysoko na liście zadań, których unikają. W końcu ta praca nie jest twórcza, nie wpływa na realne działanie oprogramowania. Dokumentacji nikt nie przeczyta, bo po co szukać odpowiedzi w dokumentacji skoro łatwiej zadać pytanie zespołowi.
Agile a dokumentacja – czyli czy możemy pominąć ten punkt?
Kiedy organizacja postanawia przejść transformację i zaimplementować podejście Agile często jest to kojarzone z brakiem konieczności pisania dokumentacji. Wreszcie można zacząć kodować zamiast opisywać przyszłą pracę i tworzyć stosy dokumentów, których nikt nigdy nie przeczyta. Skąd takie podejście? Pierwszym co nasuwa się na myśl jest jedno z twierdzeń z Manifestu Agile:
“W wyniku naszej pracy, zaczęliśmy bardziej cenić działające oprogramowanie od szczegółowej dokumentacji”.
Ciężko nie zgodzić się ze stwierdzeniem, że produkt jest bardziej wartościowy niż jego opis. Każdy klient oczekuje oprogramowania, które będzie odpowiedzią na jego potrzeby, pomoże mu osiągnąć założone cele a w dłuższej perspektywie – rozwinąć biznes. Częstym zarzutem kierowanym w stronę metodyk zwinnych jest pisanie dokumentacji pobieżnie, bądź też całkowite jej pominięcie. W końcu skoro mamy działające oprogramowanie, po co tworzyć jego szczegółowy opis post factum? A jeśli pracujemy w podejściu klasycznym – skoro zależy nam na działającym oprogramowaniu, to w jakim celu tworzyć jego opis, który z dużą dozą prawdopodobieństwa, nie będzie miał wiele wspólnego z efektem końcowym? Niestety, takie zrozumienie przytoczonego zdania jest błędne.
Produkt, projekt i dokumentacja
Warto zastanowić się czym jest projekt, czym produkt a czym dokumentacja. I czy faktycznie te 3 elementy są odrębnymi bytami. Na potrzeby tego artykułu, załóżmy, że naszym celem jest stworzenie aplikacji mobilnej, służącej do rezerwacji taksówek. Będziemy odwoływać się do tego przykładu później.
Projekt jest określonym czasowo przedsięwzięciem, w wyniku którego uzyskujemy nową, unikalną wartość. Przy planowaniu projektu powinniśmy określić wstępny zarys produktu, jego celowość i potrzebne zasoby, czyli przygotować się do uruchomienia prac projektowych. W naszym przykładzie – chcemy stworzyć aplikację mobilną, zatem możemy założyć, że będziemy potrzebować zespołu programistów, a także urządzeń mobilnych, na których sprawdzimy poprawność działania aplikacji, środowiska deweloperskiego, testowego, produkcyjnego oraz mechanizmów automatyzacji.
Następnie mamy produkt – czyli określone dobro – w formie fizycznej lub w formie usługi, będące odpowiedzią na konkretne zapotrzebowania konsumentów. W przytoczonym przykładzie będzie to, działająca zgodnie z wymaganiami, aplikacja mobilna.
Zaczynamy pracować nad dokumentacją
Mamy już określony cel, zasadność i wstępnie – zasoby. Teraz nadszedł czas na zaplanowanie pierwszych prac. Warto zorganizować “Story Jam Session”. Podczas takiego spotkania Product Owner przedstawia wizję biznesową produktu, następnie cały Zespół Deweloperski pracuje nad dookreśleniem poszczególnych elementów, jakie powinien posiadać produkt. Tego typu spotkanie jest istotne z kilku powodów – po pierwsze pozwala na wypracowanie wizji produktu wspólnej dla wszystkich stron zaangażowanych w projekt. Ponadto, taka sesja pozwala na wykorzystanie potencjału Zespołu Deweloperskiego – zebranie pomysłów, których Product Owner nie miał możliwości określić z racji np. ograniczeń technicznych. Skonfrontowanie wizji produktu z osobami, które tę wizję fizycznie będą implementować pozwala często osiągnąć ciekawe i inspirujące rezultaty, które nie pozostają bez znaczenia dla późniejszej wartości biznesowej wdrażanych rozwiązań.
Efektem końcowym “Story Jam Session” będzie wkład do stworzenia Product Backlog’u, nad którym następnie będzie pracował Product Owner. Zazwyczaj są to User Stories (US) – jedne dookreślone szczegółowo, inne jako pomysły do rozważenia, część może wymagać dalszej pracy, ponieważ nie spełnia Definition of Ready (DoR) – więcej informacji na temat DoR oraz innych terminów z zakresu Agile znajdziesz w „Przystępnym słowniku pojęć Agile” opublikowanym na naszym blogu w styczniu 2020. Popularną formą tworzenia US jest opisanie funkcjonalności oprogramowania z perspektywy użytkownika, przy jednoczesnym określeniu jej wartości biznesowej, według schematu: Jako …, chcę…, aby… . Ta prosta forma często wystarcza, aby odpowiedzieć na podstawowe pytanie: CO? Pytanie zadajemy w odniesieniu do zakresu efektu końcowego, czyli po spełnieniu jakich warunków możemy stwierdzić, że funkcjonalność oprogramowania spełnia wymagania biznesowe. Odnosząc się do przykładowej aplikacji mobilnej do obsługi rezerwacji taksówek: przykładowe pytanie CO? może brzmieć:
- Jako użytkownik po uruchomieniu aplikacji w przeciągu 10 sekund widzę na ekranie listę 3 taksówek najbliższych mojej lokalizacji, aby móc zarezerwować preferowaną.
Trudniejszą kwestią jest odpowiedź na pytanie JAK? Z punktu widzenia technologii, co musi zostać zrobione lub zaimplementowane, aby spełnić wymaganie będące odpowiedzią na pytanie CO? To jest właściwe miejsce do wykorzystania potencjału zespołu deweloperskiego. Dla podanego przykładu pytania CO? zadanego powyżej, odpowiedzią będzie określenie JAK? chcemy osiągnąć założony cel, np.:
- Pobranie danych GPS z urządzeń taksówek zalogowanych do sieci.
- Implementacja bazy X w modelu danych Y przy konfiguracji Z
- Wyliczenie odległości za pomocą algorytmu Haversine’a
- Sortowanie wyników względem najkrótszej wyliczonej drogi
- Zwrócenie pierwszych 3 wyników z sortowanej listy.
Dokumentacja techniczna powinna zawierać odpowiedź na oba pytania: CO? oraz JAK? – maksymalnie zwięzłą, treściwą i klarowną, zgodną ze słowami Einstein’a: “Jeśli nie potrafisz wyjaśnić czegoś prosto, nie rozumiesz tego wystarczająco dobrze”.
Po co nam Definition of Done?
Zatrzymajmy się na chwilę przy tworzeniu Definition of Done (DoD). Dobrze sformułowane i pełne nie tylko zapewni nam przejrzystość procesu i wskaże sposób rozwoju funkcjonalności, ale będzie pierwszym wsadem do dokumentacji projektowej. Załóżmy dla uproszczenia, że DoD do każdego zadania będzie zawierała informację o tym:
- KIEDY uznajemy funkcjonalność za wdrożoną?
- Jakie TESTY powinny zostać przeprowadzone?
- Na jakim ŚRODOWISKU funkcjonalność ma działać?
- Czy funkcjonalność została UDOKUMENTOWANA?
Zaznaczmy, że Definition of Done zawiera opis elementów jakościowych i niefunkcjonalnych, dzięki czemu możliwe jest zapewnienie odpowiedniego formatu dokumentacji niezależnie od czasu powstania przyrostu. Przykładowo dla testów: Zespół Deweloperski określa komplet testów, jakie powinny zostać przeprowadzone. Czy przeprowadzone zostaną testy wydajnościowe i funkcjonalne czy także obciążeniowe? Jakie testy automatyczne i/lub manualne? Na jakim środowisku funkcjonalność powinna zostać przetestowana i wdrożona na koniec Sprintu? Deweloperskim, testowym czy produkcyjnym? Mając określone wszystkie te wymagania w DoD wdrożenie następuje zgodnie z wcześniej przyjętym schematem, co zapewnia uporządkowanie prac. Stanowi także wsparcie dla Zespołu Deweloperskiego przy estymacji User Story, poprzez dookreślony zakres prac nad każdym zadaniem.
Pozostaje ostatnia kwestia DoD – dokumentacja. Co powinna zawierać? Zasadniczo wszystko to, co zostało zawarte już w konkretnym zadaniu, widziane przez pryzmat DoD, wraz z określeniem zmian jakie zostały wprowadzone od Planowania do Review, czyli przez cały okres pracy deweloperskiej w Sprincie. Powróćmy do naszego przykładu i rozpatrzmy to w oparciu o pytanie JAK?, odnoszące się do zadania implementacji bazy danych. Zgodnie z pierwotnym założeniem baza danych miała być oparta o domyślną konfigurację (Z). Jednak w trakcie prac okazało się, że potrzebna jest większa wydajność pod kątem pamięci, a co za tym idzie – potrzebna jest inna konfiguracja (W). Taka zmiana może być skutkiem wielu kwestii, natomiast zawsze jest wynikową pracy dewelopera nad zadaniem. Poza wcześniej wymienionym CO? oraz JAK? również ten element (czyli zmiana względem pierwotnego planu) powinien znaleźć się w dokumentacji. Dodatkowo wszystkie elementy, które pojawiły się w trakcie pracy – określone protokoły, biblioteki (o ile odbiegają od standardowych rozwiązań), raporty z testów – są tymi elementami, które może dokumentacja techniczna zawierać. Opis tych komponentów powinien być maksymalnie zwięzły i treściwy – nie piszemy elaboratu tylko dokumentację. Wystarczy, że określimy z jakich bibliotek korzystamy, nie musimy opisywać każdej linii kodu, która się do niej odnosi.
Czas na retro!
Retrospektywa to idealny moment na zrobienie inspekcji pracy wykonanej w trakcie całego Sprintu. Metod przeprowadzania Retrospektywy jest wiele, jednak zawsze warto odpowiedzieć sobie na pytanie: czy osiągnęliśmy zamierzony cel? Dobrą praktyką jest przegląd wykonanej pracy pod kątem DoD i zadanie sobie podstawowych pytań do każdej z implementowanych funkcjonalności:
- Jakie problemy pojawiły się w trakcie pracy nad tym zadaniem?
- Czym były spowodowane?
- Jak rozwiązaliśmy te problemy?
Odpowiedź na ostatnie pytanie często może być częścią naszej dokumentacji technicznej. W jaki sposób finalnie zaimplementowaliśmy funkcjonalność? Jeśli musieliśmy zmieć np. konfigurację bazy danych, nie opisujemy całej historii researchu i/lub dewelopmentu – wystarczy, że w dokumentacji określimy konfigurację końcową. W tym celu możemy dodać nawet plik konfiguracyjny.
Warto zauważyć, że podejście zwinne – w tym przypadku Scrum, ze względu na ceremonie jakimi są Planowanie oraz Retrospektywa, a także dzięki wprowadzeniu Definition of Done, wspiera tworzenie dokumentacji. Dobrze przeprowadzone spotkania, skupione na osiągnięciu określonego celu nie pomijają tworzenia dokumentacji technicznej, tak naprawdę wspomagają jej tworzenie.
Czas, czas, czas
Czy pisanie dokumentacji wymaga czasu? Oczywiście, że tak. Jak dla każdego zadania – potrzeba odpowiedniej ilości czasu, aby ją wytworzyć. Podejście zwinne sprzyja pisaniu dokumentacji, ponieważ wymaga niewielkiego nakładu pracy – w ilości i terminie jakie są niezbędne w danym momencie. Nie wymaga dokumentowania na wyrost, w odniesieniu do User Stories, które jeszcze nie zostały opracowane przez Zespół Deweloperski (nie zostały zamienione w przyrost). Dokumentacja to również element codziennej prac Zespołu Deweloperskiego, tak jak projektowanie UX, kodowanie czy testowanie. Uświadomienie sobie tego faktu jest pierwszym (ale bardzo ważnym!) krokiem na drodze do wytwarzania dokumentacji.
Dokumentacja jest także kluczowym elementem dla zespołów pracujących zdalnie. Minimum informacji, jakie powinna zawierać, wspomaga zespół w wykonywaniu codziennych zadań. Tworzy przestrzeń, gdzie wszystkie najistotniejsze informacje odnośnie przyrostu są zebrane w jednym miejscu. Brak możliwości zadania pytania osobie siedzącej obok nas, w jednym pokoju lub budynku sprawia, że czas uzyskania odpowiedzi znacząco się wydłuża. Niestety nawet najlepsze komunikatory nie dorównają rozmowie twarzą w twarz.
Dokumentacja jest także kluczowym elementem, w kwestii zmian zachodzących w samym zespole: w przypadku dołączenia nowej osoby pomaga w szybkim wdrożeniu jej w realia produktu, a także samego projektu. Jeśli natomiast deweloper odchodzi z zespołu, informacje na temat produktu nie znikają wraz z nim. Wiedza zgromadzona przez poszczególnych członków zespołu jest nieoceniona i kluczowa przy rozwoju produktu, dlatego konieczne jest niedopuszczenie do sytuacji, w której możemy tę wiedzę utracić.
Pamięciowy back-up
Dokumentację powinniśmy pisać również dla samych siebie. Praca nad niektórymi projektami czasami zajmuje wiele miesięcy, przy czym może zajść potrzeba zmiany elementów, które zostały już wytworzone i wdrożone. O wiele łatwiej sprawdzić jakie algorytmy były wykorzystane przy rozwoju danej funkcjonalności w dokumentacji niż przypominać sobie wszystkie szczegóły dewelopmentu. Wszystkie użyte technologie, zmiany i algorytmy dla wszystkich możliwych funkcjonalności są niemożliwe do zapamiętania, dlatego warto zrobić sobie „pamięciowy back-up” w postaci dokumentacji technicznej.
Scrum Master a dokumentacja
Gdzie w tym procesie jest rola dla Scrum Mastera? Wyzwaniem jest pokierowanie zespołu w stronę zrozumienia, gdzie znajduje się ich dokumentacja i doprowadzenie do sytuacji, aby zespół nie skazywał swojej pracy na zapomnienie. Zręby dokumentacji technicznej powstają w trakcie Sprintu, podczas Planowania oraz Refinement’u, gdzie zadania mogą być uszczegóławiane lub zmieniane, jak również w trakcie Retrospektywy. Zadaniem zespołu jest zebranie tych elementów w jednym miejscu i wykorzystanie ich jako punktu wejścia do sporządzenia dokumentacji technicznej. Ale to rolą Scrum Mastera jest uświadomienie zespołowi, że zrobił dokumentację podczas Sprintu. Muszą tylko zebrać ją w jednym miejscu. I nie koniecznie musi to być bagażnik samochodu typu kombi. 🙂
Zostaw komentarz