Znacie to? Dostajecie do zapoznania si\u0119 Bardzo Wa\u017cn\u0105 Dokumentacj\u0119 ver. 20 Kluczowego Systemu. Otwieracie dokument, patrzycie si\u0119 na ilo\u015b\u0107 stron jakie zosta\u0142y wyprodukowane („no, no… 150 stron, to musi by\u0107 masa informacji”) . Wi\u0119c z zapa\u0142em zabieracie si\u0119 do czytania. I..? I pora\u017cka – okazuje si\u0119, \u017ce dokument jest tak naprawd\u0119 pusty – po\u0142owa „tre\u015bci” to rysunki, kt\u00f3re nic nie wnosz\u0105, reszta to wygenerowany z automatu opis tych rysunk\u00f3w, najcz\u0119\u015bciej ca\u0142kowicie pusty lub te\u017c zaprezentowane diagramy s\u0105 banalne, informacje si\u0119 powtarzaj\u0105. Nie do\u015b\u0107 \u017ce nie ma z nich \u017cadnego po\u017cytku to jeszcze wprowadzaj\u0105 chaos informacyjny: zaciemniaj\u0105 inne, potencjalnie wa\u017cne dane, powoduj\u0105 \u017ce w masie nieistotnych danych ginie to co jest kluczowe.<\/p>\n
Czyli tym razem b\u0119dzie o jako\u015bci dokumentacji. O tym co mo\u017cna zrobi\u0107 \u017ale pisz\u0105c dokumentacj\u0119, ze wskazaniem na mo\u017cliwe przegi\u0119cia – tak co za du\u017co to niezdrowo. I o tym jak sobie poradzi\u0107 z tym tematem.<\/p>\n
<\/p>\n
W\u0142a\u015bnie, po co w\u0142a\u015bciwie ci analitycy produkuj\u0105 t\u0105 ton\u0119 modeli, dokument\u00f3w? Dokumentacja ma kilka cel\u00f3w, jednak wszystkie kr\u0119c\u0105 si\u0119 wok\u00f3\u0142 zarz\u0105dzania informacj\u0105. Przede wszystkim dokumentacja ma na celu przekazanie informacji – <\/em>umo\u017cliwienie w systematyczny i sp\u00f3jny spos\u00f3b udost\u0119pnienia jednej stronie danych kt\u00f3re posiada druga strona. Dodatkowo dokumentacja ma na celu tak\u017ce uporz\u0105dkowanie informacji<\/em> – zorganizowanie przekazywanych danych w taki spos\u00f3b aby by\u0142y czytelne, zrozumia\u0142e i sp\u00f3jne. Na koniec dokumentacja to tak\u017ce archiwizacja informacji<\/em> – czyli zarejestrowanie danych kt\u00f3re posiadamy w danym momencie, ale nie koniecznie b\u0119dziemy je pami\u0119tali za tydzie\u0144 czy za rok. Ale jeden kiepski obraz to zmarnowana strona. <\/em>Powszechnie znane powiedzenie ma te\u017c swoj\u0105 drug\u0105 stron\u0119. Je\u017celi obraz (diagram w naszym wypadku) nie zawiera istotnych informacji, wspomnianych\u00a0 w poprzednim akapicie, to nie opowiada 1000 s\u0142\u00f3w tylko zabiera niepotrzebnie miejsce. Co wi\u0119cej – nawet je\u017celi diagram zawiera jakie\u015b informacje to nie zawsze jest najlepszym sposobem do ich zaprezentowania.<\/p>\n \u015awietnym przyk\u0142adem mo\u017ce tutaj by\u0107 przekazywanie informacji, \u017ce system b\u0119dzie zbudowany wg tr\u00f3jwarstwowej architektury. Obowi\u0105zkowo w postaci rysunku wyprodukowanego w Visio przez niew\u0105tpliwie uzdolnionego artystycznie architekta. Je\u017celi odbiorcami dokumentu jest osoby IT – to taki rysunek widzieli ju\u017c 100 tysi\u0119cy razy i nic nowego im nie wniesie, je\u017celi natomiast odbiorcami s\u0105 osoby nietechniczne to i tak go nie zrozumiej\u0105. Wi\u0119c rysunek sam w sobie jest w\u0142a\u015bciwie nie potrzebny. Pro\u015bciej jest przecie\u017c napisa\u0107 „system b\u0119dzie zrealizowany w architekturze 3-warstowej” ni\u017c cyzelowa\u0107 przez godzin\u0119 rysunek pokazuj\u0105cy te abstrakcyjne warstwy.<\/p>\n Kolejnym przyk\u0142adem mog\u0105 by\u0107 banalne modele proces\u00f3w lub banalne diagramy UML. Dostajemy diagram BPMN na kt\u00f3rym przedstawiony jest „proces” sk\u0142adaj\u0105cy si\u0119 z 3 krok\u00f3w i jednego punktu decyzyjnego. Przecie\u017c to samo mo\u017cna zawrze\u0107 w jednym zdaniu („system wykonuje A, je\u017celi rezultatem jest 1 to proces przechodzi do B, a je\u017celi\u00a0 2 to przechodzi do C”). Zawarto\u015b\u0107 informacyjna jest ta sama. Na marginesie: je\u017celi powsta\u0142 taki opis procesu biznesowego to jest co\u015b nie tak z analiz\u0105 – taki byt raczej nie jest procesem biznesowym ale regu\u0142\u0105 biznesow\u0105 lub mo\u017ce przypadkiem u\u017cycia niskiego poziomu. Je\u017celi widzimy takie diagramy to problemy z analiz\u0105 mo\u017ce by\u0107 g\u0142\u0119bszy ni\u017c jej „rozwodnienie”.<\/p>\n Typowy problem dokumentacji korporacyjnych produkowanych w formie MS-dokument\u00f3w. Wi\u0119kszo\u015b\u0107 tego typu organizacji ma wypracowane wewn\u0119trzne standardy szablony dokumentacji. Te szablony powstawa\u0142y przez d\u0142ugi okres, uwzgl\u0119dniaj\u0105 wiele interes\u00f3w r\u00f3\u017cnych grup. Zawieraj\u0105 dziesi\u0105tki tabelek, list, rozdzia\u0142\u00f3w kt\u00f3re teoretycznie powinny by\u0107 wype\u0142nione w ka\u017cdym dokumencie. Oczywi\u015bcie – nikt tego nigdy nie robi w pe\u0142ni, w przypadkach kt\u00f3re s\u0105 wa\u017cne cz\u0119\u015b\u0107 z tych standard\u00f3w zostaje jako\u015b wype\u0142niona, w praktyce nigdy jednak nie zdarza si\u0119 w pe\u0142ni poprawnie wype\u0142niony dokument. W efekcie – zawarto\u015b\u0107 informacji do obj\u0119to\u015bci dokumentu jest niska – masa pustych obszar\u00f3w, kt\u00f3re zosta\u0142y przeklejone z szablonu i nigdy nie uzupe\u0142nione lub te\u017c pozostawione z domy\u015blnymi warto\u015bciami.<\/p>\n W tym wypadku problemem nie jest za ma\u0142a dok\u0142adno\u015b\u0107 ale zbyt du\u017ca szczeg\u00f3\u0142owo\u015b\u0107. Dokumentacja opisuje z detalami tematy kt\u00f3re s\u0105 oczywiste, zosta\u0142y ju\u017c okre\u015blone w innym obszarze dokumentacji lub, w innej wersji, po prostu si\u0119 niepotrzebnie powtarza.<\/p>\n Ekstremalnym przyk\u0142adem kt\u00f3ry tu przychodzi do g\u0142owy, jest dokumentacja przypadk\u00f3w u\u017cycia, jak\u0105 m\u00f3j zesp\u00f3\u0142 otrzyma\u0142 kiedy\u015b do wdro\u017cenia. Na pierwszy rzut oka dokumentacja by\u0142a bardzo rozbudowana – obejmowa\u0142a kilkadziesi\u0105t przypadk\u00f3w u\u017cycia, ze szczeg\u00f3\u0142owym rozpisaniem na scenariusze ka\u017cdego z nich, projektem GUI, modelem danych. Przy pierwszej pr\u00f3bie przeczytania okaza\u0142o si\u0119, \u017ce jednym istotnym elementem dokumentacji jest model danych. Przypadki u\u017cycia i powi\u0105zany model GUI to by\u0142 zwyczajny CRUD dla ka\u017cdej z klas modelu danych, co wi\u0119cej – ka\u017cdy przypadek przebiega\u0142 tak samo. Czyli co\u015b co mo\u017cna by zamkn\u0105\u0107 w jednym, parametryzowanym przypadku u\u017cycia i paru ekranach ze wskazaniem \u017ce ka\u017cda operacja CRUD musi przebiega\u0107 tak samo, z dok\u0142adno\u015bci\u0105 do u\u017cytej klasy i p\u00f3l prezentowanych na ekranie. Dokumentacj\u0119 mo\u017cna by skr\u00f3ci\u0107 z 30 PU do 4.<\/p>\n Dobrze udokumentowane wymagania czy system nie oznaczaj\u0105 setek stron dokumentacji, czy rozbudowanych modeli z tysi\u0105cem diagram\u00f3w. Dokumentacja musi zawiera\u0107 istotne informacje, z punktu widzenia odbiorcy, przekazane w czytelny spos\u00f3b. Je\u017celi u\u017cytkownik dokumentacji nie b\u0119dzie w m\u00f3g\u0142 uzyska\u0107 z niej wymaganych informacji, bo np. nie b\u0119dzie w stanie znale\u017a\u0107 potrzebnych mu danych w nat\u0142oku zb\u0119dnych wype\u0142niaczy, to dokumentacja nie spe\u0142ni swojej roli.<\/p>\n","protected":false},"excerpt":{"rendered":" Znacie to? Dostajecie do zapoznania si\u0119 Bardzo Wa\u017cn\u0105 Dokumentacj\u0119 ver. 20 Kluczowego Systemu. Otwieracie dokument, patrzycie si\u0119 na ilo\u015b\u0107 stron jakie zosta\u0142y wyprodukowane („no, no… 150 stron, to musi by\u0107 masa informacji”) . Wi\u0119c z zapa\u0142em zabieracie si\u0119 do czytania. I..? I pora\u017cka – okazuje si\u0119, \u017ce dokument jest tak naprawd\u0119 pusty – po\u0142owa „tre\u015bci” … Czytaj dalej Ilustrowana instrukcja oddychania w 10 krokach<\/span><\/a><\/p>\n","protected":false},"author":2,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[12,4],"tags":[21,9,25,26,7],"class_list":["post-52","post","type-post","status-publish","format-standard","hentry","category-analiza","category-narzedzia","tag-analiza-biznesowa","tag-diagram","tag-dokumentacja","tag-standardy","tag-wymagania"],"_links":{"self":[{"href":"https:\/\/jaceksalacki.pl\/index.php\/wp-json\/wp\/v2\/posts\/52","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/jaceksalacki.pl\/index.php\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/jaceksalacki.pl\/index.php\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/jaceksalacki.pl\/index.php\/wp-json\/wp\/v2\/users\/2"}],"replies":[{"embeddable":true,"href":"https:\/\/jaceksalacki.pl\/index.php\/wp-json\/wp\/v2\/comments?post=52"}],"version-history":[{"count":16,"href":"https:\/\/jaceksalacki.pl\/index.php\/wp-json\/wp\/v2\/posts\/52\/revisions"}],"predecessor-version":[{"id":409,"href":"https:\/\/jaceksalacki.pl\/index.php\/wp-json\/wp\/v2\/posts\/52\/revisions\/409"}],"wp:attachment":[{"href":"https:\/\/jaceksalacki.pl\/index.php\/wp-json\/wp\/v2\/media?parent=52"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/jaceksalacki.pl\/index.php\/wp-json\/wp\/v2\/categories?post=52"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/jaceksalacki.pl\/index.php\/wp-json\/wp\/v2\/tags?post=52"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}
\n<\/em><\/p>\nJeden obraz to 1000 s\u0142\u00f3w<\/strong><\/h2>\n
Tabelki, wsz\u0119dzie tabelki<\/h2>\n
Jeszcze jeden i jeszcze raz<\/h2>\n
Na koniec<\/h2>\n