Dokumentacja w agile’u 

Jak już wkładać kij w mrowisko, to niech to będą najbardziej niebezpieczne mrówki. Jak to jest z tą dokumentacją w podejściu zwinnym? A może dokumentacja w ogóle nie jest nam potrzebna, niezależnie od tego czy to agile, czy też nie?

Agile, czyli co

Zacznijmy od tego, że nie ma czegoś takiego jak „w adżajlu”, czy „w podejściu zwinnym”. Coś takiego jak jedna zunifikowana „metodyka agile” nie istnieje. Jest podejście, sposób myślenia, nastawienie, niektórzy nawet mówią, że filozofia.

To trochę tak, jak było z pytaniem „Jak agile radzi sobie z zależnościami?” Wykorzystaliśmy je jako temat jednego z filmów na naszym kanale na YouTube. Zainteresowanych odsyłamy tam, a my zajmiemy się dzisiejszym bohaterem, czyli dokumentacją.

No dobrze, ale zanim zaczniemy omawiać „jak”, warto byłoby wiedzieć o czym konkretnie mówimy. Niektóre metodyki definiują, co ma być dokumentowane, kiedy rzeczona dokumentacja ma powstawać, a czasami nawet w jakiej formie. Inne dyskretnie na ten temat milczą, licząc na to, że ogarnięte osoby wykształcą swoje sposoby na dokumentowanie powstających produktów i systemów.

Nie ma jednego przepisu, nie zajmiemy się więc też żadnym konkretnym podejściem, tylko rozważymy temat dokumentacji ogólnie. Bo chyba nikt o zdrowym rozsądku nie pomyślał nawet przez chwilę, że dokumentacji nie powinno być?

Dokumentacja w Agile… Manifesto

Podobnie jak do końca naszej kariery będziemy tłumaczyć, że nie ma żadnych „ceremonii Scrum„, tak samo będziemy prostować stwierdzenia o Agile Manifesto. Najczęściej słyszymy, że „przecież jest wyraźnie napisane, że nie robimy dokumentacji”. Spójrzmy więc, co konkretnie zostało napisane w tym słynnym dokumencie.

„W wyniku naszej pracy zaczęliśmy bardziej cenić (…) działające oprogramowanie od szczegółowej dokumentacji (…). Oznacza to, że elementy wypisane po prawej są wartościowe, ale większą wartość mają dla nas te, które wypisano po lewej.” – Agile Manifesto

Czyli, jeżeli mam wybrać pisanie dokumentacji bądź sprawienie, że jakiś kawałek oprogramowania działa, powinienem wybrać to drugie. Ale nigdzie nie jest powiedziane, że jeśli mam czas na obie te rzeczy, to dokumentacja powinna zostać pominięta.

Zresztą, w tym momencie wypadałoby sobie odpowiedzieć na pytanie, co konkretnie rozumiemy pod słowem „dokumentacja”? To słowo najczęściej interpretowane jest jako „dokumentacja użytkownika” albo „dokumentacja systemowa”.

Dokumentacja… użytkownika

Z dokumentacją użytkownika od zawsze mam pewien problem. Jeżeli system wymaga kilkuset stron dokumentacji, bez której nikt nie jest w stanie znaleźć nawet najbardziej podstawowej opcji, to znaczy, że system jest do bani.

Kto z Was czytał instrukcję do miksera, samochodu, telefonu komórkowego czy dowolnej aplikacji na komórkę? Jasne, są takie zastosowania, że czasami trzeba sięgnąć po instrukcję i zobaczyć jak tę jedną konkretną rzecz zrobić. I właśnie taka „instrukcja użytkownika”, w formie FAQ (najczęściej zadawanych pytań) ma sens. Dla zasady możemy też opisać podstawowy sposób poruszania się po różnych opcjach i menu, ale cała reszta powinna być intuicyjna.

Niezależnie do jakiego samochodu nie wsiądziemy, zwykle większość rzeczy robi się dokładnie tak samo. Okej, czasami pokrętło jest jednocześnie przyciskiem, a czasami przycisk okazuje się dżojstikiem, który służy do przełączania kart w menu, które wyglądają na niedostępne (Mazdo patrzę na Ciebie, to wcale nie było intuicyjne).

Po rzeczy takie jak „wyłącznie świateł oświetlających drogę do domu po zamknięciu samochodu” czy „co konkretnie oznaczają poszczególne poziomy kontroli trakcji” pewnie będziemy musieli sięgnąć do instrukcji. Podobnie jak po ciśnienie w oponach przy maksymalnym załadowaniu albo rodzaj i ilość oleju w silniku (czytaj: parametry techniczne). Natomiast na pewno producenci samochodów skupiają się na ich tworzeniu tak, aby podstawowe, codzienne czynności nie wymagały doktoratu.

I my powinniśmy iść ich śladem.

Inna dokumentacja

Do dokumentowania niektórych rzeczy zobowiązują nas ustawy, a do innych – zdrowy rozsądek. Zasada jest jednak prosta – piszmy tak mało dokumentacji, żebyśmy nie mieli problemów.

Jeśli musimy – piszmy. Jeśli wydaje nam się, że bez niej nikt nie będzie w stanie dojść o co chodzi – zróbmy ją. Jeżeli wiemy, że mamy projekt na pół roku i potem utrzymanie przejmuje klient, zapomnijmy o jakiejkolwiek dokumentacji i cieszmy się z tego, że nasze rozwiązanie jest skomplikowane. Będziemy mieć pracy na lata, bo klient nigdy nie podoła z dalszym jego rozwojem.

No dobrze, ostatnie dwa zdania to żart.

Po pierwsze, skupmy się na tym, żeby zarówno nasz kod, jak i dokumenty które powstają w ramach prac (wymagania, analizy) były na wystarczającym poziomie, żeby dalszy rozwój i utrzymanie przebiegał bez problemu. Po drugie, wszystkie mocno skomplikowane fragmenty, algorytmy i niejasne decyzje – zapiszmy i wyjaśnijmy w zrozumiały sposób. No i w końcu po trzecie – i to jest kluczowe – jak nam czegoś zaczyna brakować, to nadrabiajmy zaległości i dostosowujmy nasz proces tak, żeby braki nas nie dotykały.

Dbajmy też, żeby wszystko co powstaje było u-trzy-my-wal-ne. Unikajmy setek stron nudnego i nieaktualnego tekstu, którego nikt nie czyta. No i nie wrzucajmy zrzutów ekranu interfejsów do dokumentacji, jeżeli system jest w fazie gwałtownego rozwoju. Dziesięć osób po kolei pomyśli „przecież zmieniam tylko jedno pole, nie muszę przecież niczego aktualizować”, a potem mamy obrazki w ogóle nie przypominające produkcyjnego systemu.

Dbajmy o to, żeby mieć jakiś obraz tego, co najważniejsze i aby ten obraz był aktualny. No i kompletny.

User Stories to nie dokumentacja!

Wielokrotnie spotkałem się ze stwierdzeniem, że „User Stories są naszą dokumentacją”. Dla przypomnienia, US-y to nic innego niż wymagania zapisane w pewien konkretny sposób. I tu jeszcze może byśmy znaleźli jakąś szansę, żeby wykorzystać je do dokumentacji, gdyby nie iteracyjny sposób wytwarzania oprogramowania.

Pracując przyrostowo i iteracyjnie, nie tylko rozbudowujemy system o nowe funkcjonalności, ale rozwijamy już istniejące. Przybliżamy nasze rozwiązanie coraz bardziej i bardziej do stanu docelowego, wystarczającego do zaspokojenia potrzeby biznesowej. Każde wymaganie znajdujące się w naszym backlogu opisuje pewne przybliżenie, zmierzające w pewnym określonym kierunku.

Zadbajmy więc, żebyśmy ten kierunek i ten stan docelowy mieli gdzieś odwzorowany. Niewiele jest gorszych rzeczy od ustawy bez tekstu ujednoliconego. Jest nią bez wątpienia luźny zbiór wymagań, z których każde opisuje drobną zmianę przy braku opisu całości. To nie dokumentacja, to tylko wymagania.

I tu ktoś może zauważyć, że po co „tekst ujednolicony” do wymagania związanego np. z podstawowymi ustawieniami konta (login, język, avatar, zmiana hasła, itd.). A ja oczywiście się z tym zgodzę i cofnę się o kilka akapitów.

Dokumentujmy to, co jest nam potrzebne. Ni mniej, ni więcej.