Poprawna i efektywna dokumentacja w projektach IT

Wydawało się, że wraz ze spadkiem fascynacji podejściem „ultra zwinnym” i związanej z nim niechęci do wszelkiej dokumentacji, triumfy zacznie święcić bardziej „inżynierskie” podejście do dokumentowania projektów IT. Niestety, na podstawie rozmów z niektórymi praktykami, a w szczególności tez wygłaszanych na różnych konferencjach, muszę stwierdzić, że niekoniecznie jest to prawda. 😊

Wciąż można usłyszeć, że „dokumentacja powinna być przede wszystkim wartościowa”, „najważniejsza jest komunikacja, a nie dokumentacja” albo że „można dokumentować nawet na serwetce, jeśli tylko ma to sens”.

Trudno nie zgodzić się z tym, że dokumentacja powinna być wartościowa, a jej forma nie może być ważniejsza od treści. Problem polega jednak na tym, że podobne stwierdzenia niewiele mówią o tym, jak w praktyce należy dokumentować rozwiązania informatyczne.

Co więcej, często stanowią wygodne uzasadnienie dla rezygnacji ze sprawdzonych technik, standardów i narzędzi. Ponadto stanowią uzasadnienie dla „bylejakości” i nadmiernej improwizacji. Często też mają na celu tworzenia wrażenia, że istnieje „wiedza tajemna” dotycząca dokumentacji, dostępna jedyne dla wybranych.

Spróbujmy zatem przyjrzeć się temu zagadnieniu nieco bardziej konkretnie.

Po co nam dokumentacja?

Jak opisywałem w książce „Certyfikowany inżynier wymagań. Na podstawie IREB CPRE”, dokumentacja systemów IT ma kilka istotnych celów.

Przede wszystkim ułatwia komunikację z interesariuszami i osiąganie wspólnego zrozumienia. Ma to szczególne znaczenie w projektach, w których uczestniczy wiele osób reprezentujących różne dziedziny, role i perspektywy. Bez odpowiedniej dokumentacji komunikacja może być bardzo utrudniona i czasochłonna. Co więcej, informacje przekazywane wyłącznie ustnie są podatne na zniekształcenia, nieporozumienia i zwyczajne zapominanie. Dokumentacja pozwala również utrwalać podjęte decyzje oraz stojące za nimi uzasadnienia. Dzięki temu po pewnym czasie można nie tylko sprawdzić, jakie rozwiązanie zostało uzgodnione, ale również dlaczego wybrano właśnie takie podejście.

Kolejnym istotnym powodem tworzenia dokumentacji jest retencja wiedzy w organizacji. Projekty informatyczne trwają miesiącami, a czasem latami. Powstałe w ich wyniku rozwiązania są natomiast często utrzymywane i rozwijane przez wiele kolejnych lat, a w skrajnych przypadkach nawet dziesięcioleci. W tym czasie zmieniają się zespoły, dostawcy, technologie i osoby odpowiedzialne za poszczególne elementy systemu. Jeżeli utrzymanie i rozwój tych rozwiązań mają być efektywne, a odejście pojedynczego pracownika nie powinno oznaczać utraty znacznej części wiedzy o systemie, niezbędne jest jej odpowiednie utrwalenie.

Dokumentacja pomaga również w analizie wpływu zmian, identyfikowaniu zależności, planowaniu testów czy wdrażaniu nowych członków zespołu. Warto przy tym zauważyć, że odbiorcą dokumentacji bardzo często jest sam jej autor, który po kilku miesiącach musi przypomnieć sobie szczegóły wcześniejszych ustaleń lub logiki działania systemu. Każdy, kto po dłuższej przerwie wracał do własnych analiz, zapewne wie, o czym mówię.

Jaka powinna być poprawna dokumentacja wymagań?

Skoro wiemy już, po co tworzymy dokumentację, warto zastanowić się, jakie cechy powinna ona posiadać. Oczywiście można poprzestać na stwierdzeniach, że dokumentacja powinna być „wartościowa”, „adekwatna do potrzeb” czy „komunikować to, co ważne”.

Problem w tym, że bez zdefiniowania konkretnych kryteriów takie stwierdzenia są w zasadzie nieweryfikowalne. Co właściwie oznacza „wartościowa dokumentacja”? Jak ocenić, czy rzeczywiście spełnia swoje zadanie?

Zamiast wymyślać własne, często nieprecyzyjne definicje, proponuję skorzystać z dorobku inżynierii wymagań. Przykładowo norma ISO/IEC/IEEE 29148:2018 oraz materiały IREB CPRE przedstawiają kryteria jakości wymagań i związanych z nimi produktów pracy. Więcej o kryteriach jakości znaleźć można w jednym z wcześniejszych wpisów.

Dokumentację trzeba również utrzymywać

Wśród wymienionych w IREB CPRE kryteriów szczególną uwagę warto zwrócić na modyfikowalność. Wydaje się oczywiste, że prawie każdy zbiór wymagań i niemal każda dokumentacja rozwiązania informatycznego prędzej czy później będą podlegały zmianom. Mogą one wynikać ze zmieniających się przepisów prawa, oczekiwań interesariuszy, zmian technologicznych, modyfikacji procesów biznesowych czy rozwoju samego systemu. Dlatego dokumentację warto tworzyć z myślą nie tylko o jej bieżącym wykorzystaniu, ale również o przyszłym utrzymaniu.

Częstym problemem związanym z dokumentacją jest redundancja, czyli wielokrotne powtarzanie tych samych informacji. Powoduje ona zwiększoną pracochłonność tworzenia i utrzymania dokumentacji, a poza tym sprzyja niespójności.

Wyobraźmy sobie system, w którym przebieg procesu opisano za pomocą diagramu BPMN, wymagań opisanych tekstowo oraz procedur opisujących działania użytkownika. W pewnym momencie organizacja decyduje się zmienić pisywany proces. Analityk aktualizuje wymagania tekstowe, ale zapomina o diagramie procesu. Dokumentacja procedur również pozostaje bez zmian. W rezultacie organizacja posiada trzy źródła informacji przedstawiające różne wersje rzeczywistości.

Podobne sytuacje zdarzają się również wtedy, gdy dokumentacja przechowywana jest w wielu miejscach, nie istnieją jednoznaczne zasady jej aktualizacji albo trudno ustalić, która wersja jest aktualna.

Dlatego istotne jest nie tylko to, co dokumentujemy, ale również jak organizujemy, przechowujemy i aktualizujemy dokumentację. W tym kontekście popularne stwierdzenie, że „można dokumentować nawet na serwetce, byle miało to sens”, wydaje mi się szczególnie problematyczne. Rozumiem oczywiście, że jest to przenośnia mająca podkreślić znaczenie treści, a nie formy dokumentacji. Wydaje mi się jednak ona wybitnie szkodliwa i promująca złe praktyki.

Szkice i notatki

Nie ma nic złego w szkicach czy odręcznych notatkach. Podczas warsztatów lub spotkań analitycznych mogą one być bardzo skutecznym sposobem komunikacji. Problem pojawia się w momencie, gdy utożsamiamy taki tymczasowy artefakt z dokumentacją, która ma być wykorzystywana i rozwijana przez kolejne lata. Powodzenia życzę osobie, która będzie musiała po roku odnaleźć przysłowiową serwetkę, odczytać zapisane na niej ustalenia, a następnie zmodyfikować dokumentację, zachowując jej spójność z pozostałymi elementami opisu systemu. Osoby, którym przyszło utrzymywać dokumentację w formie „bazgrołów” w popularny narzędziu do pracy wspólnej, z pewnością wiedzą co mam na myśli 😊

Warto zatem rozróżniać dokumentację tymczasową, tworzoną przede wszystkim na potrzeby bieżącej komunikacji i budowania wspólnego zrozumienia, od dokumentacji, która powinna podlegać systematycznemu utrzymaniu. Luźne zapiski z warsztatu to nie „pełnoprawna” dokumentacja.

Po co nam narzędzia do dokumentacji wymagań?

Problemy związane z tworzeniem i utrzymaniem dokumentacji nie są niczym nowym. W odpowiedzi na nie przez lata opracowano wiele technik dokumentacyjnych, szablonów, standardów, notacji oraz dedykowanych narzędzi.

Przykładem są narzędzia CASE (ang. Computer-Aided Software Engineering), wspierające różne działania związane z inżynierią oprogramowania, w tym modelowanie i dokumentowanie rozwiązań. Dostępne są również wyspecjalizowane narzędzia do zarządzania wymaganiami, repozytoria w formie Wiki etc.

Zasadne wydaje się więc pytanie, dlaczego nie korzystać z tych rozwiązań, skoro zostały opracowane właśnie po to, aby ułatwiać realizację określonych zadań. Oczywiście można wskazać argument kosztów. Wdrożenie narzędzia wiąże się nie tylko z zakupem licencji, ale również z konfiguracją, szkoleniami czy późniejszym utrzymaniem. Jednak oceniając opłacalność takiej inwestycji, warto uwzględnić również koszty pracy specjalistów związanej z tworzeniem, wyszukiwaniem, weryfikowaniem i aktualizowaniem dokumentacji. Jeśli odpowiednio dobrane narzędzie pozwala ograniczyć te koszty, zmniejszyć liczbę błędów i ułatwić utrzymywanie spójności, jego zastosowanie może być ekonomicznie uzasadnione.

Dobór odpowiedniego narzędzia

Kluczowy wydaje świadomy dobór narzędzia do charakteru dokumentacji, skali przedsięwzięcia i sposobu jej późniejszego wykorzystania. Nie zawsze niezbędne są drogie i skomplikowane systemy. Często wystarczy coś prostszego i często bezpłatnego.

Trudno jednak uznać za racjonalne całkowite ignorowanie dostępnych rozwiązań tylko dlatego, że korzystanie z nich wymaga nieco nauki lub przyjęcia określonego standardu pracy.

Od specjalistów zajmujących się inżynierią wymagań powinniśmy przecież oczekiwać nie tylko umiejętności pozyskiwania informacji, ale również znajomości technik i narzędzi. W razie potrzeby powinniśmy oczekiwać szybkiego przystosowania się i adaptacji.

Czy standardowe notacje są istotne?

Często spotykam się także ze stwierdzeniem, że stosowanie standardowych notacji, takich jak UML czy BPMN, nie jest celem samym w sobie. Oczywiście, że nie jest! Notacje są jedynie środkiem służącym osiąganiu określonych celów. Nie oznacza to jednak, że ich wykorzystanie jest pozbawione znaczenia.

Standardowe notacje nie powstały przypadkowo. Są rezultatem wieloletnich doświadczeń, identyfikowania problemów i wypracowywania sposobów ich rozwiązywania. Zapewniają ustandaryzowany język komunikacji, określają znaczenie poszczególnych elementów oraz pomagają przedstawiać informacje w sposób uporządkowany. Dzięki temu mogą wspierać osiąganie takich kryteriów jakości dokumentacji jak spójność, zrozumiałość czy jednoznaczność.

Oczywiście stosowanie standardowych notacji niczego nie gwarantuje. Można stworzyć diagram BPMN, który będzie niepoprawny, nieczytelny lub po prostu bezużyteczny. Można też przygotować bardzo dobry model bez wykorzystania sformalizowanej notacji. Nie zmienia to jednak faktu, że standardowe notacje dostarczają sprawdzonych konstrukcji i zasad, których nie musimy każdorazowo opracowywać od początku.

Co więcej, umożliwiają odczytywanie i interpretowanie dokumentacji przez osoby, które nie uczestniczyły w jej tworzeniu. Oczywiście pod warunkiem, że znają stosowaną notację. Ma to szczególne znaczenie w dużych organizacjach, w których dokumentacja może być wykorzystywana przez wiele zespołów, również długo po zakończeniu projektu.

Oczywiście notację należy dobierać do celu i odbiorców. Nie każdy interesariusz musi znać BPMN czy UML, a nadmiernie rozbudowany model może utrudniać komunikację zamiast ją wspierać. Nie jest to jednak argument przeciwko standardom, lecz za ich świadomym i umiejętnym wykorzystaniem. Znajomość zasad gramatyki nie gwarantuje napisania dobrego tekstu. Czy oznacza to, że powinniśmy zrezygnować z gramatyki? Podobnie jest z notacjami.

Ile kosztuje brak dokumentacji?

W dyskusjach dotyczących dokumentowania rozwiązań IT często pojawia się argument, że przygotowywanie dokumentacji wymaga czasu i generuje koszty. To oczywiście prawda. Warto jednak zastanowić się również nad tym, ile kosztuje brak dokumentacji lub jej niska jakość.

Ile czasu poświęcają pracownicy na odtwarzanie wcześniejszych ustaleń? Jak długo trwa analiza działania systemu, którego logika nie została nigdzie opisana? Ile kosztuje identyfikowanie skutków zmian bez możliwości prześledzenia zależności pomiędzy wymaganiami i innymi elementami rozwiązania? Do tego dochodzą koszty nieporozumień, poprawek, ponownego wykonywania analiz czy wdrażania nowych członków zespołu.

Problem polega na tym, że koszty tworzenia dokumentacji są zazwyczaj stosunkowo łatwe do zidentyfikowania, natomiast koszty jej braku często pozostają ukryte i rozproszone pomiędzy wiele osób oraz działań.

Nie oznacza to oczywiście, że należy dokumentować wszystko, niezależnie od kosztu i rzeczywistych potrzeb. Nadmierna dokumentacja również może stanowić problem. Zwiększa koszty utrzymania, utrudnia wyszukiwanie informacji i generuje dodatkową pracę. Dlatego właściwą alternatywą dla braku dokumentacji nie jest jej maksymalizacja, lecz świadome określenie zakresu, formy i sposobu utrzymywania dokumentacji.

Moje rekomendacje

  • Pamiętaj o celach dokumentowania – twórz dokumentację tak, aby ułatwiała komunikację, pomagała osiągać wspólne zrozumienie oraz umożliwiała utrwalanie wiedzy, ustaleń i decyzji projektowych.
  • Myśl o przyszłych odbiorcach dokumentacji – pamiętaj, że często sam będziesz do niej wracać. Zadbaj więc o odpowiednią strukturę, nazewnictwo i możliwość szybkiego odnalezienia potrzebnych informacji.
  • Uwzględniaj przyszłe zmiany – stosuj techniki i narzędzia pozwalające aktualizować ją rozsądnym kosztem, bez utraty spójności i innych istotnych cech jakościowych.
  • Korzystaj ze sprawdzonych standardów, szablonów i notacji – nie staraj się na siłę wymyślać koła na nowo. Rozwiązania te powstały po to, aby odpowiadać na rzeczywiste problemy związane z dokumentowaniem i komunikowaniem informacji.
  • Dostosowuj dokumentację do potrzeb – nie każdy projekt wymaga tych samych artefaktów, narzędzi czy poziomu szczegółowości. Dobieraj je świadomie, uwzględniając zarówno bieżące potrzeby interesariuszy, jak i przewidywany sposób wykorzystania dokumentacji w przyszłości.
  • Weryfikuj jakość dokumentacji – ją na podstawie konkretnych kryteriów, zamiast ograniczać się do ogólnych stwierdzeń, że powinna być „wartościowa”.

Źródła

  • Grębski R., Kalabińska J., Certyfikowany inżynier wymagań. Na podstawie IREB CPRE. Poziom podstawowy, Helion, Gliwice 2024, ISBN 978-83-289-0976-2.
  • ISO/IEC/IEEE 29148: Systems and Software Engineering – Life Cycle Processes – Requirements Engineering, International Organization for Standardization, 2018
  • Certyfikowany specjalista inżynierii wymagań IREB, Sylabus, wersja 3.3.0, 2026.

Radek Grębski

Analityk biznesowy, inżynier wymagań, trener