Raport dla przypadków użycia

Z modelem przypadków użycia tworzonym przez analityków w programie Enterprise Architect powinno się zapoznać wielu interesariuszy projektu. Spośród nich można wymienić projektantów, programistów, ale przede wszystkim przedstawicieli klienta, takich jak kluczowi użytkownicy, eksperci dziedzinowi i inni. W związku z tym, jeśli decydujemy się na opisywanie scenariuszy przypadków użycia w formie Structured Scenario w EA - powinniśmy również zadbać o ich stronę dokumentacyjną.
Profesjonalnie przygotowany raport poprawia czytelność i odbiór wyników pracy fazy analizy.

Oznaczanie zmian pomiędzy wersjami generowanych dokumentów

Dokumentacja projektowa powstaje zazwyczaj iteracyjnie. Czyli najpierw powstaje pierwsza wersja dokumentu, która jest opiniowana. Zgłoszone uwagi do dokumentu są uwzględniane przez autora (autorów) i w odpowiedzi powstaje druga wersja dokumentu i tak dalej... W innym scenariuszu, gdy dokument opisuje działający system informatyczny - zawartość dokumentów zmienia się wraz z wprowadzanymi modyfikacjami do systemu.
Gdy opisywane rozwiązanie jest małe, wówczas adresaci dokumentacji mają szanse się orientować dokładnie w zawartości dokumentów. Jednak, gdy dokumentacja dotyczy dużego i złożonego systemu, wówczas rodzi się potrzeba odpowiedniego oznaczania zmian w dokumentacji. Dzięki takim oznaczeniom osoby, które opiniują dokument mogą ograniczyć się na przykład do opiniowania tylko i wyłącznie treści dodanych lub zmienionych w odniesieniu do ostatniej wersji.

Jeśli dokumentacja projektowa powstaje wprost w MS Office, wówczas najlepszym sposobem na oznaczanie zmian pomiędzy wersjami wydaje się:

• zastosowanie Trybu Rejestracji Zmian (ang. Track Changes),
• lub oznaczanie kolorami dodanego tekstu oraz przekreślanie tekstu usuniętego.

Jeśli jednak zespół w trosce o poprawę jakości generowanej dokumentacji i ograniczenie pracochłonności, decyduje się na generowanie dokumentacji projektowej z narzędzia Enterprise Architect - wówczas wykorzystanie Trybu Rejestracji Zmian nie jest możliwe.

Co można zrobić w takiej sytuacji?

Jak wybrać tylko właściwe elementy?

Ostatnio od kilku różnych osób dostałem zapytania dotyczące odfiltrowania tylko wybranych elementów do raportu RTF. Pytania te dotyczyły na przykład umieszczenia w raporcie elementów o określonym statusie lub przypisanych do określonej fazy. Pisałem już o tym w artykule Generowanie raportów RTF w EA, jednak postanowiłem bardziej przybliżyć temat pisząc o mechanizmie Element filters. Ta sama funkcja dotycząca filtrowania elementów została zastosowana w dwóch miejscach w EA:

• Model Search - alternatywnie do budowania zapytań SQL możliwe jest wyszukiwanie elementów (i nie tylko) w oparciu o filtry.
• Dokumentacja - filtry można zastosować w odniesieniu do definicji całego dokumentu (dostępnej z poziomu okna Resources --> Documents --> RTF Documents lub w odniesieniu do pojedynczych szablonów RTF.

Dalej skupię się na zastosowaniu Element Filters dla raportów RTF. 

Edycja szablonów RTF: Elementy spoza pakietu

W prosty sposób można umieścić w szablonie RTF opisy elementów znajdujących się w pakiecie objętym raportem. Wystarczy wstawić odpowiednie znaczniki, a następnie wybrać właściwe pola, które opisują znaczące cechy, takie jak nazwa (Name), czy opis (Notes).
Często jednak może być potrzebne wymienienie również innych elementów, które są powiązane z raportowanym pakietem poprzez kontekst. Dotyczyć to może elementów powiązanych relacjami lub obcych elementów umieszczonych na diagramach w raportowanym pakiecie. Dzięki temu raport może zawierać również (lub tylko) elementy pochodzące z innych pakietów niż raportowany.
Taki zabieg może być przydatny na przykład w sytuacji, gdy w rozdziale opisującym przypadki użycia chcemy nawiązać również do kontekstu procesów biznesowych lub komponentów aplikacji, które je realizują.

Edycja szablonów RTF

Program Sparx Enterprise Architect jest instalowany wraz z kolekcją predefiniowanych szablonów RTF. Dostęp do tych raportów jest możliwy z poziomu okna Resources. Szablony te są zebrane w grupę o nazwie System. Raport wygenerowany przy użyciu predefiniowanego szablonu jest łatwo rozpoznawalny z uwagi na zastosowanie specyficznych styli paragrafów. Chociażby wszystkie nagłówki mają odcienie koloru niebieskiego.
Taki styl może nie odpowiadać każdemu, w związku z tym sugeruję, aby traktować je jedynie jako przykłady możliwych konstrukcji, a dla celów projektowych opracować na ich podstawie własne szablony.
Jest to o tyle istotne, że predefiniowane szablony zawierają bardzo dużą ilość cech, tabel oraz pól, które mogą być nadmiarowe. Brak doświadczenia w edycji szablonów bądź po prostu ludzka niechęć do wyrzucania czegokolwiek sprawia, że wygenerowany raport przy użyciu standardowego szablonu staje się nieczytelny z uwagi na przeładowanie niepotrzebnymi informacjami.
W jednym z projektów spotkałem się z raportem wygenerowanym przy użyciu standardowego szablonu, który liczył blisko 200 stron. Ważne informacje były tak rzadko rozsiane, że samo przewijanie stawało się nieprzyjemne, a jak się pomyśli jeszcze o tym, że taki raport jest drukowany w kilku egzemplarzach, to aż żal lasów. Ten raport zamiast 200 stron bez problemu zmieściłby się na 20-30 stronach.

Virtual Reports

W programie Enterprise Architect w zakresie generowania dokumentacji w formacie RTF jest możliwość generowania tzw. raportów prostych - opartych o jeden szablon oraz raportów złożonych - opartych o więcej niż jeden szablon. Zaproponowany przeze mnie podział na typy raportów został opisany w artykule Rodzaje raportów.
Metoda wykorzystania raportów złożonych, czyli Virtual Reports może nie być czytelna dla każdego, w związku z tym postanowiłem poświęcić jej nieco miejsca.

Definicje pojęć związanych z generowaniem raportów

W artykułach opisujących funkcjonalność generowania raportów w programie Sparx Enterprise Architect pojawia się szereg pojęć, które mogą być niejasne. W związku z tym w poniższej tabeli zaprezentowano ich definicje. Należy je traktować jako moją propozycję definicji, gdyż mogą się nieco różnić od opisów dostępnych w publikacjach Sparx Systems.

Pojęcie	Definicja
Document Artifact	Element wykorzystywany m.in. przez mechanizm Virtual Report. W tym kontekście służy do przechowywania treści statycznych w formie Linked Document.
Linked Document	Dokument w formacie RTF, który jest przyporządkowany do określonego elementu. Dokument ten można edytować lub usunąć. Informacja o tym, że element posiada Linked Document prezentowana jest na diagramie w postaci literki A w prawym dolnym rogu elementu.
Master Document	Element (package element) wykorzystywany przez mechanizm Virtual Report. Do Master Document możliwe jest przypisanie głównego szablonu RTF określającego m.in. paginę czyli nagłówek i stopkę całego dokumentu.
Model Document	Element wykorzystywany przez mechanizm Virtual Report służący do zdefiniowania sekcji dokumentu. Atrybuty Model Documentu określają treść sekcji, zaś szablon RTF formę prezentacji tej treści.
Package Template	Plik XMI zawierający szablon pakietu wraz z zawartością (podpakiety, diagramy i elementy). Szablon taki służy automatyzacji tworzenia struktury pakietowej, która może być wielokrotnie powielana. Package Template może być dystrybuowany przy użyciu MDG Technology lub importowany jako plik XMI (z zastosowaniem opcji Strip GUID).
Resource Document	Definicja całego dokumentu wyjściowego dostępna w panelu Resources. Definicja ta obejmuje wszystkie opcje takie jak nazwa pliku wynikowego, Master Document, filtry itp.
Treść statyczna	Zawartość sekcji dokumentu pochodząca z Linked Document należącego do elementu typu Document Artifact. Treść statyczna w odróżnieniu od treści dynamicznych generowanych z zawartości pakietu jest sformatowana w formacie RTF, może zawierać tabele oraz elementy graficzne.
Virtual Report	Mechanizm programu Enterprise Architect służący do generowania złożonych dokumentów w formacie RTF umożliwiający wybór, grupowanie oraz ustalenie kolejności treści pochodzących z różnych pakietów i zawierających różny zakres informacyjny.

Rodzaje raportów

Program Enterprise Architect umożliwia generowanie raportów, dzięki którym diagramy oraz opisy zawartości modelu mogą być prezentowane osobom zaangażowanym w przedsięwzięcie  bez potrzeby korzystania bezpośrednio z EA.
Poniżej został przedstawiony podział na kategorie tych raportów.

Raporty HTML

Raport w formacie HTML odzwierciedla strukturę repozytorium lub strukturę wybranego drzewa pakietów, czyli podzbioru repozytorium. Istnieje możliwość zmiany domyślnego szablonu HTML poprzez edycję styli CSS. Edycja szablonu pozwala zmienić styl wyświetlania określonych cech elementów oraz ograniczyć zakres prezentowanych w raporcie cech. Czyli na przykład możemy usunąć z raportu informację o autorze diagramu, czy dacie utworzenia i poprzestać tylko na informacjach ważnych z merytorycznego punktu widzenia. Ponadto w łatwy sposób możliwa jest zmiana logo prezentowanego w prawym górnym rogu raportu. 

Sugerowane zastosowanie tego typu raportu to udostępnienie treści zawartych w modelu kierownictwu projektu lub klientowi. 

Podstawową zaletą tego typu raportów jest łatwość dostępu, gdyż nie jest konieczne instalowanie aplikacji Enterprise Architect lub EA Viewer oraz konfigurowanie dostępu do współdzielonego modelu. 

W niektórych projektach zdefiniowany raport HTML jest generowany cyklicznie i publikowany w serwisie WWW zawierającym zbiór aktualnych informacji dotyczących całego przedsięwzięcia.

Poniższy rysunek prezentuje przykładowy raport w formacie HTML.

Raporty proste

Raporty proste to inaczej raporty w formacie RTF wygenerowane przy użyciu pojedynczego szablonu specyficznego dla jednego zakresu informacyjnego. Aby wygenerować na przykład raporty opisujące wymagania, przypadki użycia oraz model danych konieczne jest zastosowanie oddzielnych szablonów specyficznych dla każdego rodzaju elementów z uwagi na ich inny zakres informacyjny.

Sugerowane zastosowania:

• Zestawienie określonego typu elementów wraz z ich cechami - może służyć np. dalszemu przetwarzaniu w MS Excel.
• Raport roboczy dla członków zespołu projektowego - może służyć np. zebraniu w jednym miejscu wszystkich elementów spełniających określone kryteria w celu walidacji i weryfikacji zbioru danych.

Podstawową zaletą takich raportów jest ich prostota, gdyż wytworzenie pojedynczego szablonu nie jest czasochłonne, a uruchomienie generowania raportu nie wymaga żadnej konfiguracji.

Raporty proste mogą być generowane przy użyciu tych samych szablonów, które są wykorzystywane w generowaniu raportów złożonych.

Poniższy rysunek przedstawia przykład raportu prostego zawierającego zestawienie wymagań funkcjonalnych.

Raporty złożone - Virtual Reports

Raport złożony umożliwia wygenerowanie kompletnego dokumentu w formacie MS Word zgodnego z szablonem projektowym wykorzystywanym również do tworzenia dokumentacji wprost w MS Word lub Open Office. Dzięki temu cała dokumentacja projektowa posiada jednolitą i spójną formę, czyli takie same:

• style paragrafów,
• stronę tytułową,
• metrykę,
• formę spisu treści,
• oraz paginę (nagłówek i stopkę).

Dokument taki może składać się z wielu sekcji, z których każda prezentuje inny zakres informacyjny charakterystyczny dla różnego rodzaju elementów modelu. Dodatkowo część treści takiego dokumentu może stanowić tzw. treść statyczną, pochodzącą z zawartości Linked Documents, czyli dokumentów RTF przechowywanych w repozytorium EA. Dokumenty takie mogą zawierać elementy graficzne oraz tabele, które trudno byłoby umieścić w opisach elementów lub pakietów. Format zawartości Linked Document może być niezależny od zastosowanych szablonów projektowych.

Sugerowane zastosowanie to generowanie kompletu dokumentacji projektowej. Zastosowanie Virtual Reports pozwala zachować spójność treści modelu oraz dokumentów, łatwość aktualizacji oraz sprawniejsze zarządzanie dokumentacją poprzez rozdzielenie treści dokumentów od formy ich prezentacji.

Aby skorzystać z tego typu raportów konieczne jest oprócz przygotowania szablonów również opracowanie odpowiedniej struktury pakietowej oraz diagramów. Przykładowy diagram, który definiuje raport złożony przedstawia poniższy rysunek.

Mechanizm Virtual Reports umożliwia dodatkowo wygenerowanie również raportu w formacie HTML. Tego typu hybryda pozwala stworzyć raport HTML, który posiada strukturę zgodną z dokumentem w formacie RTF, a nie ze strukturą pakietową repozytorium.

Poniższy rysunek przedstawia taki przykładowy raport, którego strukturę można porównać z odpowiednikiem z zamieszczonym wyżej przykładowym raportem w formacie HTML.

Generowanie raportów RTF w EA

Gdy zakończymy pracę nad opracowaniem modelu w Enterprise Architect nadchodzi moment, gdy należy podzielić się wynikami pracy z innymi członkami zespołu projektowego lub z klientem. Możemy przesłać lub udostępnić repozytorium EA, ale o wiele lepszym rozwiązaniem jest opracowanie dokumentacji, która w bardziej przejrzysty i czytelny sposób prezentuje zawartość modelu. W tym celu należy skorzystać z funkcjonalności generowania raportów w EA.

Biblioteka dokumentów w EA

W artykule Import wymagań z Linked Document opisałem mechanizm tworzenia elementów modelu wprost z dokumentów składowanych w modelu w formie Linked Documents. Wykorzystanie tego mechanizmu wymaga zaimportowania dokumentów do modelu i przypisanie ich do określonych elementów typu <<document>>. Proces taki wymaga pewnego nakładu sił, co w przypadku dużych projektów może być kłopotliwe, a poza tym użytkownicy modelu i tak mają świadomość, że dokumenty te są tylko kopią dokumentów składowanych poza modelem. Aby mieć pewność, że sięgają do właściwej treści użytkownicy i tak będą korzystać z referencyjnego repozytorium dokumentów, jakim może być np. Sharepoint lub SVN.

Zatem po co tworzyć bibliotekę dokumentów w modelu Enterprise Architect?

Mogą istnieć różne przesłanki wynikające ze specyfiki projektów. Z analitycznego punktu widzenia  wartość dodaną stanowi możliwość tworzenia relacji dokumentów do innych elementów modelu (np. Dependency, Trace) oraz możliwość łączenia poprzez hiperłącza określonych słów czy fraz z dokumentu.
Ponadto model dokumentacji może służyć do wspomagania procesów tworzenia dokumentacji projektowej poprzez zastosowanie diagramów i relacji pomiędzy dokumentami. Na przykład można zamodelować zależności prezentujące informacje o tym, który dokument (lub rozdział) wynika z jakiegoś innego dokumentu. Dzięki temu łatwiej zorientować się, czy aktualizacja jednego dokumentu pociąga za sobą konieczność aktualizacji innego dokumentu.

Osadzanie raportów RTF w MS Word

Standardowe możliwości w zakresie generowania dokumentacji projektowej w programie Enterprise Architect są wystarczające tylko dla mało wymagających użytkowników. Każdy, kto próbował w tym zakresie osiągnąć coś więcej niż standardowa konfiguracja napotykał na szereg trudności. Trudności te są związane przede wszystkim z edycją szablonów RTF.
A ja tak na przekór wszystkim najbardziej cenię sobie właśnie funkcjonalność generowania dokumentacji. Wynika to chyba z mojej dawnej pasji, którą kiedyś było DTP. Obecnie, gdy uda mi się wyprodukować ładnie wyglądający raport z EA - pękam z radości.
Zamierzam na tym blogu w kolejnych postach dzielić się z Wami doświadczeniem związanych z raportami RTF.
Pominiemy chyba proste generowanie zwykłych raportów, bo łatwo znaleźć w aplikacji polecenie, które do tego służy. Zaczniemy od opisu możliwości osadzania raportów RTF w dokumencie MS Word.