Wprowadzenie

Ten artykuł to uzupełnienie opisu: Dokument jako wymaganie.

Często jestem i ja pytany o to “Jak wyjaśnić złożone rozwiązanie techniczne interesariuszom nietechnicznym?” Jak wielu mi podobnych odpowiadam: rozmawiaj dokumentami. Sponsor projektu, przyszli użytkownicy, postrzegają swoją pracę poprzez dokumenty: ich treść i układ. Zauważyli to także inni:

A Mock-up is a slightly glorified picture, so you will be answering with at least 1001 words !

Bardzo często widuję wymagania spisywane jako tak zwana lista funkcji lub funkcjonalności. Pojęcia te mają takie definicje w języku polskim:

funkcja ?zadanie, które spełnia lub ma spełnić jakaś osoba lub rzecz?, ?możliwość wykonania określonej operacji przez urządzenie lub program komputerowy?

Funkcjonalność jest definiowana jako funkcja czegoś w jakimś systemie.

Problem

Poniżej przykład (fragment) spisu wymagań wykonany rękami przyszłych użytkowników. Jest to bardzo często stosowana forma wyrażania wymagań, i zarazem jedna z najbardziej nieskutecznych, gdyż nie tylko stanowi sobą jedynie idee pomysłu (nie da się tego chronić jako know-how) to nie daje żadnej gwarancji tego co dostarczy wykonawca. Sama tego typu lista nie pozwala także ocenić jej kompletności, spójności i niesprzeczności.

System musi posiadać wbudowanego klienta poczty elektronicznej obsługującego co najmniej protokoły IMAP i SMTP. Wysyłanie i odbiór maili odbywa się w tle (obsługa poprzez niezależny proces), w taki sposób aby nie blokować pracy użytkownika np. po utworzeniu maila i kliknięciu Wyślij, użytkownik może niezwłocznie rozpocząć tworzenie nowego maila.
Wbudowany klient poczty elektronicznej posiada następujące funkcje:
Utwórz wiadomość ? umożliwia utworzenie nowej wiadomości,
Odpowiedz ? umożliwia udzielenie odpowiedzi nadawcy wraz z cytowaniem i oznaczenie cytowanego tekstu napisanego przez nadawcę,
Odpowiedz wszystkim ? umożliwia udzielenie odpowiedzi nadawcy oraz z przesłaniem jej na pozostałe adresy email wymienione w polu Do, Do wiadomości oraz Ukryty do wiadomości wraz z cytowaniem i oznaczenie cytowanego tekstu napisanego przez nadawcę,
Prześlij dalej ? umożliwia przesłanie poczty elektronicznej kolejnemu odbiorcy,
Przenieś ? umożliwia przenoszenie poczty elektronicznej pomiędzy folderami na wybranym koncie,
Drukuj ? umożliwia wydrukowanie poczty elektronicznej,
Dołącz ? umożliwia dołączenie poczty elektronicznej do sprawy lub dokumentu,
Odbierz ? umożliwia ręczne odebranie poczty elektronicznej,
Usuń ? umożliwia usunięcie wybranej poczty elektronicznej,
Znajdź ? umożliwia wyszukanie listu w folderach poczty elektronicznej,
Rejestruj ? umożliwia rejestrację poczty elektronicznej jako dokumentu w systemie w sposób analogiczny do rejestracji dokumentu zeskanowanego.

Jak widać jest to próba projektowania wyrażona prozą. Celowo wybrałem ten fragment gdyż znakomita większość czytelników odnajdzie tu w wyobraźni znany formularz klienta poczty elektronicznej (w znakomitej większości przypadków nie jest to jednak tak proste). Cały powyższy tekst można zastąpić zrzutem ekranu, lub dowolną inną formą zobrazowania formularza poczty elektronicznej. Pozostają jednak jeszcze takie wymagania jak np. “Dołącz – umożliwia dołączenie poczty elektronicznej do sprawy lub dokumentu”. Mamy tu dwie ważne rzeczy: nietypowa funkcjonalność, jaką jest “dołączenie do sprawy” (pytanie co to znaczy) oraz sugerowanie (bo nazwano to funkcjonalnością a nie “przyciskiem”) operacji dołączenia (czego do czego). Bez definicji pojęć, np. ‘dołącz’ czy ‘rejestruj’, te wymagania są po prostu niezrozumiałe.

To – powyższe – jest namiastką tego z czym walczą firmy, które na podstawie takiego opisu mają wycenić i wykonać implementację. Czy to wina autorów tych opisów? Nie jest ich winą to, że tylko tak potrafią opisać swoje wymagania. Winą ich jest co najwyżej to, że przekazują takie jak powyższy opisy jako treść zapytania ofertowego (lub jako Opis Przedmiotu Zamówienia w przetargach), dostawcom oprogramowania (patrz Kto winien porażki projektu? Zamawiający!). Opis wymagań wyrażony językiem naturalnym jest z zasady niejednoznaczny i stanowi podstawowe zagrożenie dla projektu, o czym autorzy pisali po wnikliwych badaniach w 2019 roku .

Co można zrobić? Tylko jedną rzecz: opisać oprogramowanie nie prozą jak wyżej, a za pomocą usług aplikacji wyrażonych z pomocą formularzy i pełnej logiki ich przetwarzania oraz integracji tych usług, jeżeli jest ich więcej niż jedna. Jak to wyrazić? Z użyciem UML. Jest to możliwe, chroni know-how Zamawiającego, pozwala nadzorować developera. W efekcie projekt, jako całość może być nawet o rząd wielkości tańszy i nie trwa latami!

Dzisiaj będzie o formularzach.

Mock-up’y formularzy i dokumentów

Diagramy struktur złożonych to bardzo wygodne narzędzie do modelowania wszelkich struktur konstrukcji i mechanizmów. Diagram bardzo niedoceniany i nielubiany, bo opisuje system na dość wysokim poziomie abstrakcji co jest trudne. Jest jednak niejednokrotnie niezastąpiony i to z dwóch powodów: pozwala opisać określoną konstrukcję abstrahując od jej detali (bo ich nie jeszcze znamy, nie zaprojektowaliśmy lub nie chcemy przeciążać diagramu detalami) oraz chcemy w całym projekcie użyć formalizmów UML, czyli tworzyć model zintegrowany z pozostałymi diagramami i elementami w repozytorium projektu używanego systemu CASE. Innymi słowy: panujemy nad spójnością i niesprzecznością całości. Najczęściej diagramy te są prezentowane jako narzędzie opisu architektury ?(?UML Composite Structure Diagram Examples,? n.d.)? lub konstrukcji urządzeń mechanicznych z użyciem notacji SysML (rozszerzenie UML).

Jak już wspomniano na początku, wymagania opisywane jako cechy i funkcje aplikacji nic nie mówią ani o pracochłonności ani o tym co faktycznie ma powstać. Podobnie jest z historyjkami użytkownika (patrz wymagania): są kompletnie nieprzydatne jako wymagania i jako materiał do wyceny (ale mają wartość jako wymagania biznesowe i testy dla projektanta, a nie dla developera). Dlatego, zgodnie z tezą o problemach złośliwych: jedynym sposobem oceny problemu jest próba jego rozwiązania . To dlatego przed rozpoczęciem implementacji należy projektować. Szablony formularzy i ich logika, to kluczowa część projektu i jedyna zrozumiała dla Zamawiającego jego część.

Jednak jednym z odwiecznych problemów na etapie analizy i projektowania jest właśnie dokumentowanie szablonów dokumentów i formularzy. Ogólnie struktury informacji (dokumenty) można podzielić na dwa typy: dokumenty strukturalne i niestrukturalne. Strukturalne to formularze, w których jedyną treścią są nazwane wartości (pola i ich wartości). Niestrukturalne to teksty zawierające kluczowe dane w swojej treści, jednak nie są to typowe formularze składające się wyłącznie z nazwanych pól.

Dokumenty strukturalne można modelować z pomocą diagramu struktur złożonych. 2009 roku proponowano takie oto podejście:

Powyższy diagram to właśnie Diagram Struktur Złożonych pokazujący strukturę i zawartość formularza w formie, która układem treści może, w dużym przybliżeniu, obrazować przyszły układ treści na ekranie. Z uwagi na to, że diagram ten ten jest integralną częścią modelu, można już na tym etapie używać poprawnych, i kontrolowanych słownikiem, nazw atrybutów i ich wartości. Tak więc mamy tu kompletne wymaganie wyrażone jako formularz. Jest on (powinien być) także częścią modelu dziedziny systemu. Jako, że tak wyrażony formularz to klasyfikator UML, na podstawie takiej jego postaci można wygenerować go także jako strukturę XML.

Do budowania formularzy stosuję prosty profil UML opracowany w 1998 roku . Graficznie wygląda to tak:

Przykładowy formularz, np. wniosek urlopowy, może zostać tak udokumentowany:

• słowniki lub zbiory (lista województw, ciąg 20 do 30 znaków alfanumerycznych, 4 cyfrowa liczba parzysta, itp.)
• typy strukturalne (np. adres to: kod, miasto, ulica, posesja, lokal)
• typ wyliczeniowy czyli enumeracja (zamknięte, niemodyfikowalne w przyszłości listy wartości atrybutu, np. nazwy dni tygodnia, miesięcy)

Enumeracja jest często mylona ze słownikiem (listą, kolekcją). Podstawowa różnica między słownikiem a enumeracją polega na tym, że słownik jest (może być) modyfikowany w toku korzystania z oprogramowania, a enumeracja (nie powinna być) nigdy.

Formularz ekranowy (szablon dokumentu) może mieć także postać niestrukturalną. Wniosek urlopowy może być także tekstem, w postaci takiej jak np. ta poniżej (nieco inne pola):

Taki formularz, także stanowiący wymaganie, można pokazać jako uproszczony 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 prototypie szare pola to miejsca na wprowadzane dane (znaczniki XML) i w tym miejscu mozna w dokumentacji wpisywać pojęcia ze słownika np. tak: “urlop [typ urlopu] w dniach od [data początku] do [data końca]”.

Tu warto nawiązać do baz danych NoSQL. Jest pewna różnica między plikami XML zorientowanymi na dane (mapowane często na kolumny baz SQL) i na dokumenty. Poniżej dwa przykłady:

Tu także widać, że forma dokumentowa jest prostsza w zapisie, w konsekwencji także prostsza w przetwarzaniu i zapisie w bazie dokumentowej.

Podsumowanie

Stosowanie modelowania już na etapie analiz i projektowania jest dobrze sprawdzoną i skuteczną praktyką, od wielu lat często wykorzystywaną w projektach opartych o metodykę MDA/MBSE. Kluczowym powodem dodatkowego stosowania XML jest fakt osadzenia tej notacji na modelach pojęciowych i ontologii oraz możliwość zastosowania słownika od początku projektu (patrz także Platform Independent Model, PIM):

Opisana tu metoda wymaga dodatkowej wiedzy i narzędzi CASE i jest nadal rzadko stosowana, ale nie jest jednak prawdą, że “nikt tak nie robi” (patrz literatura). Metoda ta daje jednak ogromną przewagę jakościową uzyskanego efektu, nad specyfikacjami wyrażanymi językiem naturalnym lub nieformalnymi szkicami. Ta przewaga ma swoje źródło w tym, że tak dokumentowany projekt jest od samego początku, w całości, doskonale kontrolowany narzędziem CASE. Osiągnięcie celu, jakim jest spójność, kompletność i niesprzeczność specyfikacji wymagań wyrażonej w postaci modelu, odbywa się znacznie niższym nakładem pracy (koszt), a ryzyko niespójności praktycznie zerowe. Dlatego zarówno wycena implementacji, jak i sama już potem implementacja, są łatwe. Wykonanie takiej dokumentacji trwa maksimum trzy miesiące, niezależnie od wielkości projektu (patrz artykuł o cyklu życia zamiast wymagań).

Dla zainteresowanych informacjami technicznymi napisałem wcześniej krótki tekst Dokumenty przetwarzane jako struktury XML oraz opisywanie ich z użyciem notacji UML.

Źródła