Dokument czy mapa?

…czyli o różnicy między zapisywaniem dokumentu z wymaganiami, a tworzeniem mapy historyjek.

Tworząc oprogramowanie często zaczynamy od jakiegoś konceptu lub wyobrażenia – próbujemy określić, co nasz system ma robić albo jaki problem ma on rozwiązywać. Bardzo często narzędziem do zapisania tego konceptu staje się edytor tekstu. Tworzymy dokument, który opisuje kształt naszego rozwiązania. Bardzo często dokument ten otrzymuje tytuł „Analiza wymagań systemu XYZ”.

W samym pomyśle zapisania koncepcji lub wymagań nie ma nic zdrożnego. Natomiast często w praktyce bywa tak, że praca nad systemem oparta o obszerny dokument tekstowy niesie za sobą niepożądane skutki uboczne…

Pierwszym problemem, na który się napotykamy, jest czytelność długich dokumentów.

Bardzo naturalnym odruchem osoby piszącej dokument jest umieszczenie w nim wszystkiego, co wie. Powstały dokument może zawierać na przykład takie sekcje:

• Business Problem Statement
• Current Business Process
• Scope Statement
• Key Business Objectives
• Project Completion Criteria
• Risks & Limitations
• Assumptions
• Functional & Non-Functional Requirements
• Cost and scheduling parameters
• New/Modified Business Process
• Training
• Stakeholder List
• Quality Measures

I znowu – spisanie tych wszystkich rzeczy z reguły jest pożyteczne. Problem zaczyna się w momencie, kiedy ta osoba przychodzi do zespołu programistów i mówi „tutaj jest 150-stronicowy dokument opisujący nasz system, możecie zaczynać pracę”. Programiści to najczęściej bardzo pragmatyczni ludzie, którzy szukają odpowiedzi na pytanie „to jak ten system ma działać?”. Dlatego z reguły nie czytają całego dokumentu, tylko przewijają go do rozdziału „wymagania funkcjonalne” i rozpoczynają swoją pracę. A jak czegoś nie rozumieją, to albo czytają inne rozdziały, albo – co zdarza się znacznie częściej… – idą do analityka i zadają mu pytania.

Bardzo szybko w naszym dokumencie pojawiają się zmiany, które jeszcze zmniejszają czytelność dokumentu.

Szanse na to, że stworzony dokument pozostanie nie będzie się zmieniał, są praktycznie zerowe. Zawsze wprowadzamy do niego zmiany. Pojawia się wówczas pytanie, w jaki sposób oznaczać zmiany w dokumencie. Spotkałem się z kilkoma sposobami rozwiązania tego problemu.

Niektórzy umieszczają dokument w systemie kontroli wersji typu SVN czy GIT – wtedy co prawda mamy dostęp do pełnej historii zmian dokumentu, ale w praktyce nikomu nie chce się pobierać starych rewizji, żeby podejrzeć, co się zmieniło. Inni oznaczają zmiany w każdej nowej rewizji innym kolorem tekstu – ale po dziesiątej wersji dokument zaczyna przypominać tęczę, powoli kończą się kolory i zaczynamy mieć problemy z odróżnieniem zmian jasnoróżowych od ciemnopomarańczowych. Jeszcze inni używają funkcji „Track Changes” wbudowanej w Microsoft Word – ale jeżeli ilość zmian w dokumencie jest duża, to ten mechanizm również sprawia, że czytanie kolejnych dopisków i skreśleń staje się koszmarem. Chyba w najlepszej sytuacji są osoby umieszczające dokumentację na stronach opartych o wiki (Confluence czy systemy oparte na MediaWiki) – wtedy mamy możliwość dość łatwego i szybkiego przeglądania zmian w kolejnych wersjach.

Kolejną cechą dokumentów jest to, że promują one tryb pracy oparty o coś, co po angielsku nazywa się „handovers”. Jeżeli analityk lub zespół analityków ma na celu wytworzenie dobrej jakości dokumentu, to często zdarza się, że zamyka się w swoim pokoiku i pracuje nad dokumentem „aż będzie gotowy i wystarczająco dobry”. Dopiero wówczas dokument jest pokazywany i przekazywany reszcie zespołu.

W momencie gdy implementacja systemu już trwa, pojawia się pokusa, żeby potraktować dokument analizy jako opis funkcji systemu – przecież tam mamy już wszystko zapisane. Niestety, bardzo często okazuje się, że funkcje opisane w dokumencie, możemy podzielić na trzy kategorie:

• funkcje, które są opisane w dokumencie i zostały tak zaimplementowane w naszym systemie,
• funkcje, które są opisane w dokumencie, ale zostały zaimplementowane w systemie inaczej – tylko nikt nie zmienił dokumentacji,
• funkcje, które są opisane w dokuemncie, ale nie są nigdzie zaimplementowanie.

Innymi słowy – treść dokumentu oraz faktyczne działanie budowanego systemu zaczynają się coraz bardziej rozchodzić w różnych kierunkach…

 

Pomocą w rozwiązaniu tych wszystkich problemów jest zastosowanie innego formatu zapisywania wymagań – zamiast umieszczać wymagania w dokumencie tekstowym, możemy umieścić je na mapie historyjek (User Story Map). Żeby łatwiej zobaczyć różnice między dokumentem a mapą, posłużmy się małym przykładem.

 

Przykład wymagań zapisanych w dokumencie:

REQ-1	System raportów umożliwia stworzenie raportu „Release Dashboard”
REQ-1.1	Raport „Release Dashboard” zawiera następujące dane: nazwę release’u, datę rozpoczęcia, datę planowanego wydania, liczbę projektów, liczbę zadań oraz liczbę błędów zawartych w wydaniu.
REQ-1.2	Raport „Release Dashboard” zawiera wykres ilości błędów w czasie. Wykres składa się z trzech linii: całkowita ilość błędów, ilość rozwiązanych błędów, ilość nierozwiązanych błędów.
REQ-1.3	Raport „Release Dashboard” zawiera wykres godzin, które pracownicy zarejestrowali na zadania związane z wydaniem.
REQ-2	System raportów umożliwia stworzenie raportu „Release Timesheet”
REQ-2.1	Raport „Release Timesheet” zawiera wszystkie projekty związane z wydaniem.
REQ-2.2	Dla każdego z projektów w raporcie „Release Timesheet” raport prezentuje ilośc godzin zaraportowanych na projekt.
REQ-2.3	Dla każdego z projektów w raporcie „Release Timesheet” system prezentuje listę osób, które pracowały nad projektem oraz sumę godzin, którą każda z tych osób zaraportowała na projekt.
REQ-3	System raportów umożliwia dostęp do raportów wygenerowanych w przeszłości – istnieje możliwość zapisania raportu w archiwum, wyświetlenia listy zapisanych raportów oraz wyświetlania wybranego raportu z listy.

Natomiast mapa historyjek użytkownika dla tego samego systemu może wyglądać na przykład tak:

Po wybraniu jednej z historyjek pokazuje się jej pełen opis:

Co zmienia zastosowanie takiej mapy zamiast opisu tekstowego? Po pierwsze, mapa jest czytelniejsza od dokumentu poprzez zastosowanie różnych poziomów abstrakcji. Pierwszy poziom (niebieskie karteczki) zawiera najważniejsze elementy czy funkcje systemu. Drugi poziom (żółte karteczki) rozpisuje je bardziej szczegółowo. Trzeci poziom rozpisuje szczegóły funkcjonalności. A detale ukrywają się w szczegółach karty – możemy tam umieszczać również przykłady, załączniki lub rysunki. Możemy patrzeć na mapę jako na całość (i wtedy szczegóły nas nie rozpraszają) albo możemy wgłębić się szczegóły dotyczące jakiejś grupy historyjek.

Zastosowanie w opisie historyjki formatu „jako… chciałbym… aby…” naturalnie kieruje uwagę osób rozwijających system na użytkownika tegoż systemu i na jego potrzeby. Różnica między stwierdzeniami „system musi…” a „jako użytkownik systemu chciałbym…” wydaje się niewielka – ale czasami ta drobna różnica pomaga deweloperom wczuć się w punkt widzenia użytkownika, dla którego tworzymy system.

Mając mapę historyjek, możemy bardzo łatwo połączyć ją z planem rozwoju naszego systemu. Wystarczy dodać do niej poziome linie, które będą odzwierciedlać kolejne wydania lub iteracje systemu – i przez proste przenoszenie karteczek możemy zaplanować kolejność implementacji naszych historii. Może to wyglądać na przykład tak:

W pierwszym sprincie chcemy wykonać podstawowe wersje obu raportów. W drugim sprincie rozwijamy raport „Release Timesheet”. W trzecim sprincie rozwijamy raport „Release Dashboard”. I nie wiemy jeszcze, kiedy zaimplementujemy dostęp do archwialnych raportów.

Jeżeli mamy wizję rozwoju systemu w czasie, możemy oszczędzić sobie czas poprzez rozpisywanie szczegółów tylko tych historyjek, które chcemy rozwijać w najbliższym czasie. Natomiast te rzeczy, które chcemy robić w nieokreślonej przyszłości, mogą być opisane bardzo zgrubnie. Jak będziemy widzieć, że zbliża się czas ich realizacji, to rozrysujemy sobie szczegóły. Ale może też zdarzyć się tak, że w ogóle zrezygnujemy z implementacji tej funkcjonalności i jej szczegóły nie będą nam do niczego potrzebne.

To trochę tak jak z posługiwaniem się mapą w terenie. Mamy mapę całej okolicy – ale najbardziej nas interesuje najbliższy odcinek naszej wycieczki.

Tworzenie mapy historyjek jest znakomitym ćwiczeniem dla całego zespołu. Na takim warsztacie zjawia się analityk w roli eksperta od budownego systemu – natomiast rozpisanie historyjek staje się zadaniem całego zespołu. Co prawda takie działanie może być mniej efektywne od tworzenia mapy przez jedną osobę – ale chodzi o coś innego niż o efektywność. Efektem tego warsztatu jest wspólne zrozumienie przez wszystkich członków zespołu co i w jakim celu chcemy zbudować.

Czy można osiągnąć takie wspólne zrozumienie przez wspólne pisanie dokumentu z wymaganiami? Być może jest to możliwe, ale nigdzie jeszcze tego nie widziałem…

Kolejną rzeczą, która daje nam mapa historyjek jest, brak pokusy traktowania jej jako „prawdy ostatecznej” lub traktowanie jej jako dokumentacji powykonawczej systemu. Mapa z definicji jest dynamiczna i koncentruje się na przyszłości. Jeżeli chcemy mieć opis „jak działa nasz system”, najlepiej jest tworzyć go razem z rozwojem kodu.

Dość często zdarza się, że zespoły wieszają mapę historyjek na ścianie, żeby mieć stały wzgląd w plan rozwoju naszego systemu. I nie spotkałem jeszcze zespołu, który by drukował i wieszał na ścianie dokument z wymaganiami.

 

Oczywiście mapy nie są pozbawione wad. Działają one świetnie, jeżeli budowany przez nas system opiera się na interakcjach z użytkownikiem. Wtedy możemy sobie wyobrazić efekt działania poszczególnych historyjek użytkownika. Natomiast mapa będzie dużo mniej efektywna w momencie, kiedy nasz system jest zorientowany na masowe przetwarzanie danych. Zapisywanie wymagań jako „Jako użytkownik systemu chciałbym aby pole 14 komunikatu ISO8583 było zapisane w polu TRANSACTION_DATE hurtowni danych” jest niepotrzebnym narzutem – zwłaszcza w przypadku kiedy takich pól w standardzie ISO8583 mamy ponad setkę…

Zgrubne zapisywanie przyszłych historyjek może być zarówno zaletą, jak i wadą. W momencie kiedy nasz system dynamicznie się zmienia, warto jest skupiać się na najbliższej przyszłości, bo wiemy że im dalej, tym więcej niepewności. Ale może być również tak, że chcemy mieć dokładnie rozpisane przyszłe funkcje systemu, żeby na przykład zminimalizować ryzyko pojawienia się niespodziewanych zmian architektonicznych.

 

Pomimo tych wad zastosowanie map powinno przynieść wymierne konkretne korzyści. Budowanie systemu często przypomina podróż w nieznane terytoria. A tak się jakoś składa, że w podróży wygodniej nam się posługiwać mapą niż opisem typu „…ścieżka wedle trzech buczków, co stoją nad przesieką, a tam zaraz dalej leszczyna. Jak iść prosto, to będzie jedna polanka, potem druga i trzecia, ale trzecia z błotem, lewą stroną trzeba obejść, i zaraz góreczka niewielka, na niej jeżyny…”.