Ilustrowana instrukcja oddychania w 10 krokach

Znacie to? Dostajecie do zapoznania się Bardzo Ważną Dokumentację ver. 20 Kluczowego Systemu. Otwieracie dokument, patrzycie się na ilość stron jakie zostały wyprodukowane („no, no… 150 stron, to musi być masa informacji”) . Więc z zapałem zabieracie się do czytania. I..? I porażka – okazuje się, że dokument jest tak naprawdę pusty – połowa „treści” to rysunki, które nic nie wnoszą, reszta to wygenerowany z automatu opis tych rysunków, najczęściej całkowicie pusty lub też zaprezentowane diagramy są banalne, informacje się powtarzają. Nie dość że nie ma z nich żadnego pożytku to jeszcze wprowadzają chaos informacyjny: zaciemniają inne, potencjalnie ważne dane, powodują że w masie nieistotnych danych ginie to co jest kluczowe.

Czyli tym razem będzie o jakości dokumentacji. O tym co można zrobić źle pisząc dokumentację, ze wskazaniem na możliwe przegięcia – tak co za dużo to niezdrowo. I o tym jak sobie poradzić z tym tematem.

Na początek – po co nam dokumentacja?

Właśnie, po co właściwie ci analitycy produkują tą tonę modeli, dokumentów? Dokumentacja ma kilka celów, jednak wszystkie kręcą się wokół zarządzania informacją. Przede wszystkim dokumentacja ma na celu przekazanie informacji – umożliwienie w systematyczny i spójny sposób udostępnienia jednej stronie danych które posiada druga strona. Dodatkowo dokumentacja ma na celu także uporządkowanie informacji – zorganizowanie przekazywanych danych w taki sposób aby były czytelne, zrozumiałe i spójne. Na koniec dokumentacja to także archiwizacja informacji – czyli zarejestrowanie danych które posiadamy w danym momencie, ale nie koniecznie będziemy je pamiętali za tydzień czy za rok.

Jeden obraz to 1000 słów

Ale jeden kiepski obraz to zmarnowana strona. Powszechnie znane powiedzenie ma też swoją drugą stronę. Jeżeli obraz (diagram w naszym wypadku) nie zawiera istotnych informacji, wspomnianych  w poprzednim akapicie, to nie opowiada 1000 słów tylko zabiera niepotrzebnie miejsce. Co więcej – nawet jeżeli diagram zawiera jakieś informacje to nie zawsze jest najlepszym sposobem do ich zaprezentowania.

Świetnym przykładem może tutaj być przekazywanie informacji, że system będzie zbudowany wg trójwarstwowej architektury. Obowiązkowo w postaci rysunku wyprodukowanego w Visio przez niewątpliwie uzdolnionego artystycznie architekta. Jeżeli odbiorcami dokumentu jest osoby IT – to taki rysunek widzieli już 100 tysięcy razy i nic nowego im nie wniesie, jeżeli natomiast odbiorcami są osoby nietechniczne to i tak go nie zrozumieją. Więc rysunek sam w sobie jest właściwie nie potrzebny. Prościej jest przecież napisać „system będzie zrealizowany w architekturze 3-warstowej” niż cyzelować przez godzinę rysunek pokazujący te abstrakcyjne warstwy.

Kolejnym przykładem mogą być banalne modele procesów lub banalne diagramy UML. Dostajemy diagram BPMN na którym przedstawiony jest „proces” składający się z 3 kroków i jednego punktu decyzyjnego. Przecież to samo można zawrzeć w jednym zdaniu („system wykonuje A, jeżeli rezultatem jest 1 to proces przechodzi do B, a jeżeli  2 to przechodzi do C”). Zawartość informacyjna jest ta sama. Na marginesie: jeżeli powstał taki opis procesu biznesowego to jest coś nie tak z analizą – taki byt raczej nie jest procesem biznesowym ale regułą biznesową lub może przypadkiem użycia niskiego poziomu. Jeżeli widzimy takie diagramy to problemy z analizą może być głębszy niż jej „rozwodnienie”.

Tabelki, wszędzie tabelki

Typowy problem dokumentacji korporacyjnych produkowanych w formie MS-dokumentów. Większość tego typu organizacji ma wypracowane wewnętrzne standardy szablony dokumentacji. Te szablony powstawały przez długi okres, uwzględniają wiele interesów różnych grup. Zawierają dziesiątki tabelek, list, rozdziałów które teoretycznie powinny być wypełnione w każdym dokumencie. Oczywiście – nikt tego nigdy nie robi w pełni, w przypadkach które są ważne część z tych standardów zostaje jakoś wypełniona, w praktyce nigdy jednak nie zdarza się w pełni poprawnie wypełniony dokument. W efekcie – zawartość informacji do objętości dokumentu jest niska – masa pustych obszarów, które zostały przeklejone z szablonu i nigdy nie uzupełnione lub też pozostawione z domyślnymi wartościami.

Jeszcze jeden i jeszcze raz

W tym wypadku problemem nie jest za mała dokładność ale zbyt duża szczegółowość. Dokumentacja opisuje z detalami tematy które są oczywiste, zostały już określone w innym obszarze dokumentacji lub, w innej wersji, po prostu się niepotrzebnie powtarza.

Ekstremalnym przykładem który tu przychodzi do głowy, jest dokumentacja przypadków użycia, jaką mój zespół otrzymał kiedyś do wdrożenia. Na pierwszy rzut oka dokumentacja była bardzo rozbudowana – obejmowała kilkadziesiąt przypadków użycia, ze szczegółowym rozpisaniem na scenariusze każdego z nich, projektem GUI, modelem danych. Przy pierwszej próbie przeczytania okazało się, że jednym istotnym elementem dokumentacji jest model danych. Przypadki użycia i powiązany model GUI to był zwyczajny CRUD dla każdej z klas modelu danych, co więcej – każdy przypadek przebiegał tak samo. Czyli coś co można by zamknąć w jednym, parametryzowanym przypadku użycia i paru ekranach ze wskazaniem że każda operacja CRUD musi przebiegać tak samo, z dokładnością do użytej klasy i pól prezentowanych na ekranie. Dokumentację można by skrócić z 30 PU do 4.

Na koniec

Dobrze udokumentowane wymagania czy system nie oznaczają setek stron dokumentacji, czy rozbudowanych modeli z tysiącem diagramów. Dokumentacja musi zawierać istotne informacje, z punktu widzenia odbiorcy, przekazane w czytelny sposób. Jeżeli użytkownik dokumentacji nie będzie w mógł uzyskać z niej wymaganych informacji, bo np. nie będzie w stanie znaleźć potrzebnych mu danych w natłoku zbędnych wypełniaczy, to dokumentacja nie spełni swojej roli.

Dodaj komentarz

Twój adres e-mail nie zostanie opublikowany. Wymagane pola są oznaczone *