Wprowadzenie

Ten arty­kuł to uzu­peł­nie­nie opi­su: Dokument jako wyma­ga­nie.

Często jestem i ja pyta­ny o to ​„Jak wyja­śnić zło­żo­ne roz­wią­za­nie tech­nicz­ne inte­re­sa­riu­szom nie­tech­nicz­nym?” Jak wie­lu mi podob­nych odpo­wia­dam: roz­ma­wiaj doku­men­ta­mi. Sponsor pro­jek­tu, przy­szli użyt­kow­ni­cy, postrze­ga­ją swo­ją pra­cę poprzez doku­men­ty: ich treść i układ. Zauważyli to tak­że inni:

A Mock-up is a sli­gh­tly glo­ri­fied pic­tu­re, so you will be answe­ring with at least 1001 words ! 

Bardzo czę­sto widu­ję wyma­ga­nia spi­sy­wa­ne jako tak zwa­na lista funk­cji lub funk­cjo­nal­no­ści. Pojęcia te mają takie defi­ni­cje w języ­ku polskim: 

funk­cja ?zada­nie, któ­re speł­nia lub ma speł­nić jakaś oso­ba lub rzecz?, ?moż­li­wość wyko­na­nia okre­ślo­nej ope­ra­cji przez urzą­dze­nie lub pro­gram komputerowy?

Funkcjonalność jest defi­nio­wa­na jako funk­cja cze­goś w jakimś systemie. 

Problem

Poniżej przy­kład (frag­ment) spi­su wyma­gań wyko­na­ny ręka­mi przy­szłych użyt­kow­ni­ków. Jest to bar­dzo czę­sto sto­so­wa­na for­ma wyra­ża­nia wyma­gań, i zara­zem jed­na z naj­bar­dziej nie­sku­tecz­nych, gdyż nie tyl­ko sta­no­wi sobą jedy­nie idee pomy­słu (nie da się tego chro­nić jako know-how) to nie daje żad­nej gwa­ran­cji tego co dostar­czy wyko­naw­ca. Sama tego typu lista nie pozwa­la tak­że oce­nić jej kom­plet­no­ści, spój­no­ści i niesprzeczności. 

System musi posia­dać wbu­do­wa­ne­go klien­ta pocz­ty elek­tro­nicz­nej obsłu­gu­ją­ce­go co naj­mniej pro­to­ko­ły IMAP i SMTP. Wysyłanie i odbiór maili odby­wa się w tle (obsłu­ga poprzez nie­za­leż­ny pro­ces), w taki spo­sób aby nie blo­ko­wać pra­cy użyt­kow­ni­ka np. po utwo­rze­niu maila i klik­nię­ciu Wyślij, użyt­kow­nik może nie­zwłocz­nie roz­po­cząć two­rze­nie nowe­go maila.
Wbudowany klient pocz­ty elek­tro­nicz­nej posia­da nastę­pu­ją­ce funk­cje:
Utwórz wia­do­mość ? umoż­li­wia utwo­rze­nie nowej wia­do­mo­ści,
Odpowiedz ? umoż­li­wia udzie­le­nie odpo­wie­dzi nadaw­cy wraz z cyto­wa­niem i ozna­cze­nie cyto­wa­ne­go tek­stu napi­sa­ne­go przez nadaw­cę,
Odpowiedz wszyst­kim ? umoż­li­wia udzie­le­nie odpo­wie­dzi nadaw­cy oraz z prze­sła­niem jej na pozo­sta­łe adre­sy ema­il wymie­nio­ne w polu Do, Do wia­do­mo­ści oraz Ukryty do wia­do­mo­ści wraz z cyto­wa­niem i ozna­cze­nie cyto­wa­ne­go tek­stu napi­sa­ne­go przez nadaw­cę,
Prześlij dalej ? umoż­li­wia prze­sła­nie pocz­ty elek­tro­nicz­nej kolej­ne­mu odbior­cy,
Przenieś ? umoż­li­wia prze­no­sze­nie pocz­ty elek­tro­nicz­nej pomię­dzy fol­de­ra­mi na wybra­nym kon­cie,
Drukuj ? umoż­li­wia wydru­ko­wa­nie pocz­ty elek­tro­nicz­nej,
Dołącz ? umoż­li­wia dołą­cze­nie pocz­ty elek­tro­nicz­nej do spra­wy lub doku­men­tu,
Odbierz ? umoż­li­wia ręcz­ne ode­bra­nie pocz­ty elek­tro­nicz­nej,
Usuń ? umoż­li­wia usu­nię­cie wybra­nej pocz­ty elek­tro­nicz­nej,
Znajdź ? umoż­li­wia wyszu­ka­nie listu w fol­de­rach pocz­ty elek­tro­nicz­nej,
Rejestruj ? umoż­li­wia reje­stra­cję pocz­ty elek­tro­nicz­nej jako doku­men­tu w sys­te­mie w spo­sób ana­lo­gicz­ny do reje­stra­cji doku­men­tu zeskanowanego.

Jak widać jest to pró­ba pro­jek­to­wa­nia wyra­żo­na pro­zą. Celowo wybra­łem ten frag­ment gdyż zna­ko­mi­ta więk­szość czy­tel­ni­ków odnaj­dzie tu w wyobraź­ni zna­ny for­mu­larz klien­ta pocz­ty elek­tro­nicz­nej (w zna­ko­mi­tej więk­szo­ści przy­pad­ków nie jest to jed­nak tak pro­ste). Cały powyż­szy tekst moż­na zastą­pić zrzu­tem ekra­nu, lub dowol­ną inną for­mą zobra­zo­wa­nia for­mu­la­rza pocz­ty elek­tro­nicz­nej. Pozostają jed­nak jesz­cze takie wyma­ga­nia jak np. ​„Dołącz – umoż­li­wia dołą­cze­nie pocz­ty elek­tro­nicz­nej do spra­wy lub doku­men­tu”. Mamy tu dwie waż­ne rze­czy: nie­ty­po­wa funk­cjo­nal­ność, jaką jest ​„dołą­cze­nie do spra­wy” (pyta­nie co to zna­czy) oraz suge­ro­wa­nie (bo nazwa­no to funk­cjo­nal­no­ścią a nie ​„przy­ci­skiem”) ope­ra­cji dołą­cze­nia (cze­go do cze­go). Bez defi­ni­cji pojęć, np. «dołącz» czy «reje­struj», te wyma­ga­nia są po pro­stu niezrozumiałe.

To – powyż­sze – jest namiast­ką tego z czym wal­czą fir­my, któ­re na pod­sta­wie takie­go opi­su mają wyce­nić i wyko­nać imple­men­ta­cję. Czy to wina auto­rów tych opi­sów? Nie jest ich winą to, że tyl­ko tak potra­fią opi­sać swo­je wyma­ga­nia. Winą ich jest co naj­wy­żej to, że prze­ka­zu­ją takie jak powyż­szy opi­sy jako treść zapy­ta­nia ofer­to­we­go (lub jako Opis Przedmiotu Zamówienia w prze­tar­gach), dostaw­com opro­gra­mo­wa­nia (patrz Kto winien poraż­ki pro­jek­tu? Zamawiający!). Opis wyma­gań wyra­żo­ny języ­kiem natu­ral­nym jest z zasa­dy nie­jed­no­znacz­ny i sta­no­wi pod­sta­wo­we zagro­że­nie dla pro­jek­tu, o czym auto­rzy pisa­li po wni­kli­wych bada­niach w 2019 roku .

Co moż­na zro­bić? Tylko jed­ną rzecz: opi­sać opro­gra­mo­wa­nie nie pro­zą jak wyżej, a za pomo­cą usług apli­ka­cji wyra­żo­nych z pomo­cą for­mu­la­rzy i peł­nej logi­ki ich prze­twa­rza­nia oraz inte­gra­cji tych usług, jeże­li jest ich wię­cej niż jed­na. Jak to wyra­zić? Z uży­ciem UML. Jest to moż­li­we, chro­ni know-how Zamawiającego, pozwa­la nad­zo­ro­wać deve­lo­pe­ra. W efek­cie pro­jekt, jako całość może być nawet o rząd wiel­ko­ści tań­szy i nie trwa latami! 

Dzisiaj będzie o formularzach. 

Mock-up’y formularzy i dokumentów

Diagramy struk­tur zło­żo­nych to bar­dzo wygod­ne narzę­dzie do mode­lo­wa­nia wszel­kich struk­tur kon­struk­cji i mecha­ni­zmów. Diagram bar­dzo nie­do­ce­nia­ny i nie­lu­bia­ny, bo opi­su­je sys­tem na dość wyso­kim pozio­mie abs­trak­cji co jest trud­ne. Jest jed­nak nie­jed­no­krot­nie nie­za­stą­pio­ny i to z dwóch powo­dów: pozwa­la opi­sać okre­ślo­ną kon­struk­cję abs­tra­hu­jąc od jej deta­li (bo ich nie jesz­cze zna­my, nie zapro­jek­to­wa­li­śmy lub nie chce­my prze­cią­żać dia­gra­mu deta­la­mi) oraz chce­my w całym pro­jek­cie użyć for­ma­li­zmów UML, czy­li two­rzyć model zin­te­gro­wa­ny z pozo­sta­ły­mi dia­gra­ma­mi i ele­men­ta­mi w repo­zy­to­rium pro­jek­tu uży­wa­ne­go sys­te­mu CASE. Innymi sło­wy: panu­je­my nad spój­no­ścią i nie­sprzecz­no­ścią cało­ści. Najczęściej dia­gra­my te są pre­zen­to­wa­ne jako narzę­dzie opi­su archi­tek­tu­ry ?(?UML Composite Structure Diagram Examples,? n.d.)? lub kon­struk­cji urzą­dzeń mecha­nicz­nych z uży­ciem nota­cji SysML (roz­sze­rze­nie UML).

Jak już wspo­mnia­no na począt­ku, wyma­ga­nia opi­sy­wa­ne jako cechy i funk­cje apli­ka­cji nic nie mówią ani o pra­co­chłon­no­ści ani o tym co fak­tycz­nie ma powstać. Podobnie jest z histo­ryj­ka­mi użyt­kow­ni­ka (patrz wyma­ga­nia): są kom­plet­nie nie­przy­dat­ne jako wyma­ga­nia i jako mate­riał do wyce­ny (ale mają war­tość jako wyma­ga­nia biz­ne­so­we i testy dla pro­jek­tan­ta, a nie dla deve­lo­pe­ra). Dlatego, zgod­nie z tezą o pro­ble­mach zło­śli­wych: jedy­nym spo­so­bem oce­ny pro­ble­mu jest pró­ba jego roz­wią­za­nia . To dla­te­go przed roz­po­czę­ciem imple­men­ta­cji nale­ży pro­jek­to­wać. Szablony for­mu­la­rzy i ich logi­ka, to klu­czo­wa część pro­jek­tu i jedy­na zro­zu­mia­ła dla Zamawiającego jego część.

Jednak jed­nym z odwiecz­nych pro­ble­mów na eta­pie ana­li­zy i pro­jek­to­wa­nia jest wła­śnie doku­men­to­wa­nie sza­blo­nów doku­men­tów i for­mu­la­rzy. Ogólnie struk­tu­ry infor­ma­cji (doku­men­ty) moż­na podzie­lić na dwa typy: doku­men­ty struk­tu­ral­ne i nie­struk­tu­ral­ne. Strukturalne to for­mu­la­rze, w któ­rych jedy­ną tre­ścią są nazwa­ne war­to­ści (pola i ich war­to­ści). Niestrukturalne to tek­sty zawie­ra­ją­ce klu­czo­we dane w swo­jej tre­ści, jed­nak nie są to typo­we for­mu­la­rze skła­da­ją­ce się wyłącz­nie z nazwa­nych pól. 

Dokumenty struk­tu­ral­ne moż­na mode­lo­wać z pomo­cą dia­gra­mu struk­tur zło­żo­nych. 2009 roku pro­po­no­wa­no takie oto podejście:

Powyższy dia­gram to wła­śnie Diagram Struktur Złożonych poka­zu­ją­cy struk­tu­rę i zawar­tość for­mu­la­rza w for­mie, któ­ra ukła­dem tre­ści może, w dużym przy­bli­że­niu, obra­zo­wać przy­szły układ tre­ści na ekra­nie. Z uwa­gi na to, że dia­gram ten ten jest inte­gral­ną czę­ścią mode­lu, moż­na już na tym eta­pie uży­wać popraw­nych, i kon­tro­lo­wa­nych słow­ni­kiem, nazw atry­bu­tów i ich war­to­ści. Tak więc mamy tu kom­plet­ne wyma­ga­nie wyra­żo­ne jako for­mu­larz. Jest on (powi­nien być) tak­że czę­ścią mode­lu dzie­dzi­ny sys­te­mu. Jako, że tak wyra­żo­ny for­mu­larz to kla­sy­fi­ka­tor UML, na pod­sta­wie takiej jego posta­ci moż­na wyge­ne­ro­wać go tak­że jako struk­tu­rę XML.

Do budo­wa­nia for­mu­la­rzy sto­su­ję pro­sty pro­fil UML opra­co­wa­ny w 1998 roku . Graficznie wyglą­da to tak:

Przykładowy for­mu­larz, np. wnio­sek urlo­po­wy, może zostać tak udokumentowany: 

• słow­ni­ki lub zbio­ry (lista woje­wództw, ciąg 20 do 30 zna­ków alfa­nu­me­rycz­nych, 4 cyfro­wa licz­ba parzy­sta, itp.) 
• typy struk­tu­ral­ne (np. adres to: kod, mia­sto, uli­ca, pose­sja, lokal)
• typ wyli­cze­nio­wy czy­li enu­me­ra­cja (zamknię­te, nie­mo­dy­fi­ko­wal­ne w przy­szło­ści listy war­to­ści atry­bu­tu, np. nazwy dni tygo­dnia, miesięcy) 

Enumeracja jest czę­sto mylo­na ze słow­ni­kiem (listą, kolek­cją). Podstawowa róż­ni­ca mię­dzy słow­ni­kiem a enu­me­ra­cją pole­ga na tym, że słow­nik jest (może być) mody­fi­ko­wa­ny w toku korzy­sta­nia z opro­gra­mo­wa­nia, a enu­me­ra­cja (nie powin­na być) nigdy. 

Formularz ekra­no­wy (sza­blon doku­men­tu) może mieć tak­że postać nie­struk­tu­ral­ną. Wniosek urlo­po­wy może być tak­że tek­stem, w posta­ci takiej jak np. ta poni­żej (nie­co inne pola):

Taki for­mu­larz, tak­że sta­no­wią­cy wyma­ga­nie, moż­na poka­zać jako uprosz­czo­ny XML w postaci:

<wniosek_urlopowy>
<pracodawca>nazwa firmy</pracodawca>
Wniosek Urlopowy
Na podstawie art. 167 Kodeksu Pracy wnoszę o udzielenie urlopu w trybie "na żądanie" w terminie od
<data_początku_urlopu>xxxx.xx.xx</data_początku_urlopu> do  <data_końca_urlopu>xxxx.xx.xx</data_końca_urlopu> t.j. <liczba_dni_urlopu>xxx </liczba_dni_urlopu> dni. 
Jednocześnie oświadczam, że dotychczas wykorzystałem  <liczba_wykorzystanych_dni_urlopu>xxx </liczba_wykorzystanych_dni_urlopu> dni urlopu.
<pracownik>
<imię_pracownika>imię  </imię_pracownika> 
<nazwisko_pracownika>nazwisko <nazwisko_pracownika> 
</pracownik> 
Podstawa prawna: Ustawa z dnia 26 czerwca 1974, Kodeks Pracy (dziennik ustaw rok 2018, poz 917)
</wniowek_urlopowy>

Oznaczone na powyż­szym pro­to­ty­pie sza­re pola to miej­sca na wpro­wa­dza­ne dane (znacz­ni­ki XML) i w tym miej­scu mozna w doku­men­ta­cji wpi­sy­wać poję­cia ze słow­ni­ka np. tak: ​„urlop [typ urlo­pu] w dniach od [data począt­ku] do [data końca]”.

Tu war­to nawią­zać do baz danych NoSQL. Jest pew­na róż­ni­ca mię­dzy pli­ka­mi XML zorien­to­wa­ny­mi na dane (mapo­wa­ne czę­sto na kolum­ny baz SQL) i na doku­men­ty. Poniżej dwa przykłady: 

Tu tak­że widać, że for­ma doku­men­to­wa jest prost­sza w zapi­sie, w kon­se­kwen­cji tak­że prost­sza w prze­twa­rza­niu i zapi­sie w bazie dokumentowej. 

Podsumowanie

Stosowanie mode­lo­wa­nia już na eta­pie ana­liz i pro­jek­to­wa­nia jest dobrze spraw­dzo­ną i sku­tecz­ną prak­ty­ką, od wie­lu lat czę­sto wyko­rzy­sty­wa­ną w pro­jek­tach opar­tych o meto­dy­kę MDA/MBSE. Kluczowym powo­dem dodat­ko­we­go sto­so­wa­nia XML jest fakt osa­dze­nia tej nota­cji na mode­lach poję­cio­wych i onto­lo­gii oraz moż­li­wość zasto­so­wa­nia słow­ni­ka od począt­ku pro­jek­tu (patrz tak­że Platform Independent Model, PIM): 

Opisana tu meto­da wyma­ga dodat­ko­wej wie­dzy i narzę­dzi CASE i jest nadal rzad­ko sto­so­wa­na, ale nie jest jed­nak praw­dą, że ​„nikt tak nie robi” (patrz lite­ra­tu­ra). Metoda ta daje jed­nak ogrom­ną prze­wa­gę jako­ścio­wą uzy­ska­ne­go efek­tu, nad spe­cy­fi­ka­cja­mi wyra­ża­ny­mi języ­kiem natu­ral­nym lub nie­for­mal­ny­mi szki­ca­mi. Ta prze­wa­ga ma swo­je źró­dło w tym, że tak doku­men­to­wa­ny pro­jekt jest od same­go począt­ku, w cało­ści, dosko­na­le kon­tro­lo­wa­ny narzę­dziem CASE. Osiągnięcie celu, jakim jest spój­ność, kom­plet­ność i nie­sprzecz­ność spe­cy­fi­ka­cji wyma­gań wyra­żo­nej w posta­ci mode­lu, odby­wa się znacz­nie niż­szym nakła­dem pra­cy (koszt), a ryzy­ko nie­spój­no­ści prak­tycz­nie zero­we. Dlatego zarów­no wyce­na imple­men­ta­cji, jak i sama już potem imple­men­ta­cja, są łatwe. Wykonanie takiej doku­men­ta­cji trwa mak­si­mum trzy mie­sią­ce, nie­za­leż­nie od wiel­ko­ści pro­jek­tu (patrz arty­kuł o cyklu życia zamiast wyma­gań).

Dla zain­te­re­so­wa­nych infor­ma­cja­mi tech­nicz­ny­mi napi­sa­łem wcze­śniej krót­ki tekst Dokumenty prze­twa­rza­ne jako struk­tu­ry XML oraz opi­sy­wa­nie ich z uży­ciem nota­cji UML.

Źródła