Struktury formularzy jako forma wyrażania wymagań

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: 

Formularz Wniosku urlo­po­we­go wyra­żo­ny jako Diagram struk­tur zło­żo­nych UML. Linia prze­ry­wa­ną ozna­cza się ele­ment (atry­but) o zna­nej już roli (celu uży­cia) ale nie zna­nych deta­lach. Stereotyp «Document» w UML ozna­cza treść (dane) w posta­ci w peł­ni zro­zu­mia­łej dla czło­wie­ka. Wartości atry­bu­tów nale­ży tak­że defi­nio­wać (to będą regu­ły kon­tro­li popraw­no­ści). Powinny to być:
  • 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)
  • enu­me­ra­cje (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):

(makie­ta ekra­nu, opra­co­wa­nie własne)

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: 

XML w for­mie zorien­to­wa­nej na dane. .
XML w for­mie zorien­to­wa­nej doku­men­to­wo. .

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

Papamarkos, G., Zamboulis, L., & Poulovassilis, A. (2015). Xml Databases. School of Computer Science and Information Systems, Birkbeck College, University of London. http://www.dcs.bbk.ac.uk/~sven/adm08/xmlDBs.pdf
Booch, G., Christerson, M., Fuchs, M., & Koistinen, J. (1999). UML XML Mapping Schema. 8.
Rittel, H. W. J., & Webber, M. M. (2014). Dylematy ogól­nej teo­rii pla­no­wa­nia. Zarządzanie publicz­ne, 1, 13.
Šilingas, D., & Butleris, R. (2009). Towards imple­men­ting a fra­me­work for mode­ling softwa­re requ­ire­ments in MagicDraw UML. Information Technology and Control, 38(2).
Šenkýř, D., & Kroha, P. (2019). Problem of Incompleteness in Textual Requirements Specification: Proceedings of the 14th International Conference on Software Technologies, 323 – 330. https://​doi​.org/​1​0​.​5​2​2​0​/​0​0​0​7​9​7​8​0​0​3​2​3​0​330
uml​-dia​grams​.org. (n.d.). Examples of UML com­po­si­te struc­tu­re dia­grams – Bank ATM, Apache Tomcat 7 web server, Observer design pat­tern. [UML Diagrams]. UML Composite Structure Diagram Examples. Retrieved August 8, 2020, from https://​www​.uml​-dia​grams​.org/​c​o​m​p​o​s​i​t​e​-​s​t​r​u​c​t​u​r​e​-​e​x​a​m​p​l​e​s​.​h​tml
Biron, P. V. (2001). XML Schema Part 2: Datatypes. Http://Www. W3. Org/TR/Xmlschema‑2/, 107.
Brambilla, M., Cabot, J., & Wimmer, M. (2012). Model-dri­ven softwa­re engi­ne­ering in prac­ti­ce. Morgan & Claypool.

Inne artykuły na podobny temat

image_print(wydruk PL)

Komentarze

  1. Jarosław Żeliński 22 października 2021 at 18:25

    Anonimowe zapy­ta­nie:
    czy są przy­kła­dy jak napi­sać wypeł­nić wzór tabe­li np : bada­ny obszar: ryzy­ko: mecha­nizm kon­tro­l­ny, zabezpieczenie:Sposób weryfikacji,testy. potrze­bu­ję przy­kła­do­wy wzór,z góry dzię­ku­ję za udzie­le­nie wskazówek.”

    tak, tego typu wyma­ga­nia i pro­jekt zara­zem, doku­men­tu­je­my jak powyżej.

Dodaj komentarz

Twój adres email nie zostanie opublikowany

Komentuj i zadawaj pytania autorowi.

Identyfikator *
E-mail *
Witryna internetowa

Witryna wykorzystuje Akismet, aby ograniczyć spam. Dowiedz się więcej jak przetwarzane są dane komentarzy.