W świecie IT temat dokumentacji zawsze powodował ożywione dyskusje. Niektórzy twierdzą, że jest ona niezbędna w procesie tworzenia oprogramowania, podczas gdy inni są zdania, że to strata czasu i zasobów. Wraz z rozwojem metodyk zwinnych, ten temat często powraca i powoduje duże emocje. Czy zatem dokumentacja jest naprawdę niezbędna w procesie tworzenia oprogramowania i po co jest nam potrzebna?
Dokumentacja i Agile
Tworzenie oprogramowania z wykorzystaniem metodyk zwinnych (Agile) jest często kojarzone z brakiem dokumentacji projektowej, ponieważ mogłaby ona ograniczać zwinność i elastyczność zespołu. To popularne błędne przekonanie wynika z niezrozumienia Manifestu Agile, który idealnie podsumowuję filozofię stojącą za metodykami zwinnymi. W końcu jedna z czterech głównych zasad brzmi "cenimy bardziej działające oprogramowanie nad szczegółową dokumentację".
Jednak czy to całkowicie umniejsza znaczenie dokumentacji? Absolutnie nie! W interpretacji manifestu często pomijany jest komentarz do wyżej wspomnianych zasad, który wyjaśnia, że choć Agile kładzie nacisk na pewne aspekty pracy, to nie neguje przy tym innych. Wyraźnie wskazuje to na wartość klasycznego podejścia do tworzenia oprogramowania, w którym idzie on w parze z tworzeniem dokumentacji.
Jaką dokumentację można stworzyć?
Zdefiniujmy, co rozumiemy przez dokumentację. W kontekście tworzenia oprogramowania, dokumentacja odnosi się do wszelkich pisemnych lub wizualnych materiałów, które opisują projekt, funkcjonalność, wykorzystanie systemu i/lub procesów.
Główne dwie kategorie to dokumentacja produktu i procesu. Chociaż obydwa rodzaje dokumentacji są ważne, służą różnym celom i są tworzone na różnych etapach powstawania produktu.
Dokumentacja procesu
Dokumentacja procesu odnosi się do dokumentacji opisującej procesy i procedury wykorzystywane do tworzenia i utrzymywania oprogramowania. Służy ona do zapewnieniu, że wszyscy zaangażowani w proces rozumieją, w jaki sposób zadania mają być wykonywane i jak należy utrzymywać pożądaną jakość. Dokumentacja procesu może zawierać takie elementy jak:
- standardy kodowania,
- procedury testowania,
- zasady kontroli wersji,
- wytyczne dotyczące code review,
- harmonogramy,
- zasoby,
- ryzyko,
- plany projektu,
- harmonogramy,
- budżety,
- raporty statusu,
- plany zarządzania ryzykiem.
Dokumentacja produktu
Dokumentacja produktu odnosi się do dokumentacji tworzonej dla samego oprogramowania. Można ją dalej podzielić na dokumentację dla użytkowników końcowych i dokumentację systemową.
Dokumentacja użytkownika jest używana, aby pomóc użytkownikom zrozumieć, jak zainstalować, skonfigurować i używać oprogramowania. Może zawierać takie rzeczy jak instrukcje obsługi i przewodniki instalacji.
Dokumentacja systemowa ma na celu pomóc programistom zrozumieć, w jaki sposób oprogramowanie zostało zaprojektowane i zbudowane. Zwykle składa się z dokumentu opisującego wymagania, projektu, architektury, kodu źródłowego, specyfikacji technicznych, wytycznych dotyczących testowania, dokumentacji API i wskazówek dotyczących utrzymania. Jednym z najczęściej bagatelizowanych dokumentów jest ten dotyczący wymagań. Dlaczego? Wiele osób twierdzi, że “o tym można zdecydować później”... A takie podejście generuje wiele problemów oraz konieczność wprowadzania dodatkowych iteracji z poprawkami, których można było uniknąć. Dlatego w Primotly przykładamy bardzo dużą wagę do dokumentacji tworzonej na samym początku współpracy i staramy się dokładnie poznać wymagania klienta.
Jak podchodzimy do dokumentacji w Primotly?
Dokumentacja produktu
W naszej pracy kierujemy się zasadami Scrum, dostosowując je do naszych potrzeb. Elastycznie podchodzimy do potrzeb każdego klienta, zachowując przy tym podstawowe procedury usprawniające procesy. Ważnym krokiem w budowaniu z nami produktów jest Initial Workshop, na których zbieramy wszystkie informacje potrzebne do sporządzenia wstępnej dokumentacji projektu. Na tym etapie padną pytania o:
- ogólną działalność klienta,
- krótko- i długoterminowe cele biznesowe,
- wymagania funkcjonalne,
- wymagania niefunkcjonalne (np. wymagania sprzętowe lub technologiczne),
- planowane integracje zewnętrzne,
- możliwe ograniczenia czasowe,
- przypadki użycia,
- potrzeby w zakresie UX i UI.
Na podstawie warsztatów tworzona jest pierwsza wersja dokumentacji potrzebnej do oszacowania czasu pracy nad projektem. Czasami pierwsza wersja staje się ostateczną podstawą do prac projektowych, natomiast jeśli klient musi przemyśleć niektóre części, jest ona uzupełniana podczas kolejnych warsztatów.
Choć podstawowe elementy są takie same dla każdego klienta, wstępna dokumentacja często różni się spisem treści i liczbą stron. Wynika to ze złożoności projektu, który może wymagać określenia dodatkowych wymagań już na tym etapie - na przykład rodzaju generowanych raportów czy potrzebnych formularzy.
Każdy klient znajdzie w swojej dokumentacji następujące informacje:
- Krótki opis klienta, jego działalności, rynku i grupy docelowej.
- Cele biznesowe projektu.
- Listę wymagań funkcjonalnych popartą, w razie potrzeby, odpowiednimi materiałami uzupełniającymi, takimi jak przypadki użycia lub diagramy BPMN.
- Lista zewnętrznych integracji, na przykład z obecnie używanymi programami.
- Lista wymagań niefunkcjonalnych.
Taki zbiór informacji jest dobrą podstawą do estymacji czasu i kosztów oraz wstępnego zaplanowania prac projektowych.
Jeśli chodzi o pozostałe części dokumentacji systemu – korzystamy z zaawansowanych narzędzi, takich jak Stoplight i GitHub, aby tworzyć dokumentację na bieżąco, co przekłada się pozytywnie na stosunek poświęconego czasu do efektu.
Dokumentacja procesów
Nie oczekuj od nas wielotomowej księgi z niezrozumiałymi opisami procesów i procedur. W naszej pracy priorytetem jest dobra komunikacja, a taki dokument na pewno by jej nie usprawnił.
Zamiast tego korzystamy z dedykowanych rozwiązań ułatwiających pracę, które wielokrotnie przetestowaliśmy we współpracy z klientami. Jira czy Linear pozwalają nam szybko zaprezentować plany czy szacunki, Confluence i Miro pomagają w roadmappingu, a notatki ze spotkań przechowujemy na współdzielonym dysku, dzięki czemu każda osoba zaangażowana w projekt może mieć dostęp do najnowszych wersji dokumentów.
Ważne jest, aby pamiętać, że poziom szczegółowości zawarty w każdym rodzaju dokumentacji będzie się różnić w zależności od potrzeb projektu i konkretnego klienta.
Dokumentacja w Agile
Choć dokumentacja nie jest głównym elementem zwinnego podejścia do tworzenia oprogramowania, to nadal jest niezbędna. Kluczem jest posiadanie elastycznego i usprawnionego podejścia oraz wykorzystanie dokumentacji jako narzędzia do komunikacji i współpracy. W ten sposób zespoły mogą zapewnić, że tworzą właściwe oprogramowanie w sposób wydajny i skuteczny.
