Rozpoczynając moją pracę z Enterprise Architect, miałem wrażenie że stanowi on jedynie narzędzie do rysowania diagramów. Moje zdanie zmieniło się, gdy odkryłem pełne możliwości tego narzędzia. Generowanie dokumentacji na podstawie modeli analitycznych, tworzenie złożonych i powiązanych relacjami modeli oraz wiele innych. Dzisiejszy wpis o podstawach generowania dokumentacji pokaże Ci jak na podstawie modelu generować dokumentację WORD (a także PDF i RTF).

Dlaczego się tego nauczyłem

Zacznijmy od podstaw. Jako analityk, jak wielu zacząłem swoją pracę od tworzenia dokumentacji w Word, ze względu na łatwość obsługi oraz dostępność. Przy pewnym projekcie na 2 dni przed oddaniem końcowej wersji analizy do klienta “coś” się stało z dokumentem. Prawdopodobnie uszkodziły się odnośniki, style, wkleiły się nowe rozdziały z innych części dokumentu reasumując, totalny bałagan. Niestety dokument (który zawierał najnowsze zmiany) musiałem przekazać do klienta w wyznaczonym terminie i nie było możliwości jego zmiany.

Całą noc i większość kolejnego dnia porównywałem poprzednie wersje z notatkami i szyłem dokument na nowo. W tamtym czasie również studiowałem i w dniu oddania dokumentu miałem kolokwium. Dokument oddałem w terminie, aczkolwiek kolokwium nie zaliczyłem z braku czasu na naukę.( Szef zadowolony, ale dwójka w dzienniku pozostała.)

Ze względu na te zdarzenie zacząłem szukać, czy można jakoś uniknąć takiej sytuacji w przyszłości? Odpowiedzią było wykorzystanie narzędzia do modelowania oraz generowania dokumentacji. Ze względu na cenę, dostępność i kilka innych czynników wybrałem Enterprise Architect. Dzięki niemu mogę skupić się na modelowaniu biznesu i jego potrzeb, bez konieczności poświęcania czasu na zarządzanie dokumentem Word. W dodatku dostosowanie oraz generowanie dokumentacji na podstawie modelu zajmuje dużo mniej czasu oraz daje większą elastyczność.

Od czego zacząć generowanie dokumentacji?

Zacznij od wyboru podejścia do generowania dokumentacji i przemyślenia struktury repozytorium. Kolejnym krokiem jest przygotowanie struktury dokumentu, szablonów i pozostałych elementów do generowania dokumentacji (o których w przyszłych artykułach).

Układ repozytorium

Pierwszym krokiem, jest stworzenie modelu analitycznego w repozytorium Enterprise Architect. Model musi być uporządkowany i zawierać elementy, które mają trafić do późniejszej dokumentacji. Naturalnym podejściem na początek jest utworzenie struktury pakietów zgodnie z twoim szablonem dokumentu Word. Pozwoli to Tobie na generowanie dokumentacji bez znajomości zaawansowanych funkcji.

Dwa podejścia do generowania

Znam dwa podejścia do generowania dokumentacji. Dość znacząco się różnią, wymagają innego podejścia do tworzenia szablonów oraz mają inny wpływ na komfort pracy z repozytorium. Podejścia te to:

1. Generowanie dokumentacji z użyciem diagramu dokumentacji i jego elementów.
2. Generowanie dokumentacji na podstawie pakietu z użyciem złożonego szablonu dokumentacji (szablon RTF).

Pierwsze podejście zakłada skorzystanie z dedykowanego diagramu oraz elementów pozwalających nam zdefiniowanie kolejnych rozdziałów w dokumencie i przypisanie do nich szablonu RTF. Preferuję ten sposób tworzenia dokumentacji, ponieważ pozwala na generowanie dokumentacji, bez zaawansowanej znajomości tworzenia szablonów. Podejście to zostanie opisane w dalszej części artykułu.

Drugie podejście zakłada stworzenie wielopoziomowego szablonu RTF z wykorzystanie fragmentów i innych elementów składających się na szablon RTF. W związku z tym podejście to wymaga dobrej znajomości tworzenia szablonów i zachowanie struktury repozytorium w niezmienionej formie. Każda zmiana struktury dokumentu lub repozytorium wymusza zmianę szablonu dokumentacji. W dodatku ogranicza wykorzystanie pewnych funkcji dostępnych w Enterprise Architect, jak chociażby generowanie wybranego fragmentu dokumentu (skraca to czas generowania dużych dokumentów).

Diagram dokumentacji

W ramach diagramów Enterprise Architect stworzono dedykowany diagram “ModelDocument”. Pozwala on na stworzenie struktury dokumentu. Diagram ten znajdziesz w lokalizacji [Diagram] UML Extended -> Model Document (Documentation dla 13,5 wersji EA i wcześniejszych).

W ramach diagramu mamy dedykowaną listę elementów używanych do definiowania struktury dokumentu.

Jak widzisz elementów, które można wykorzystać jest dużo. Na potrzeby podstaw generowania dokumentacji wykorzystamy Master Document oraz Model Document.

Skoroszyt dokumentu

<<Master document>> stanowi “skoroszyt” w ramach, którego zarządzamy rozdziałami, przepisujemy szablon RTF (“papier projektowy” zawierający numerowanie, nagłówek, stopkę itd.), wybieramy styl czcionek, okładkę, wygląd spisu treści i wiele innych. Gdy utworzymy tego typu element powstanie dedykowany Element package na diagramie dokumentacji oraz w Project Browser. 

Jak widzisz w ramach pakietu <<master document>> został utworzony automatycznie diagram dokumentacji (“Wstępna Analiza Biznesowa”). W ramach tego diagramu (oraz pakietu) tworzymy elementy Model document, stanowiące kolejne sekcje naszego dokumentu (np. “<model document> Cel projektu”).

Rozdziały dokumentu

<<Model document>> to element służący do zdefiniowania sekcji dokumentu. Sekcje dokumentu tworzymy poprzez przypisanie do atrybutów wybranych pakietów z Project Browser (poprzez przeciągniecie wybranego pakietu z Project Browse na obraz Model Document na diagramie). 

Gdy dodamy pakiety kolejny krokiem jest dobieranie odpowiedniego szablonu RTF (RTF Template)(Uwaga gdy nie wybierzesz szablonu zostanie przypisany domyślny szablon “Model Report”). Szablon RTF to schemat, który pozwoli na wygenerowanie poszczególnych sekcji dokumentu zgodnie z założonym standardem graficznym oraz spodziewanymi opisami. Wykorzystać tutaj można wbudowane lub utworzone samodzielnie szablony RTF. Wybranie szablonu można zrealizować dla elementu Model document w oknie Properties -> Tags -> RTFTemplate -> Wybór szablonu z listy. [Czasami po utworzeniu szablonu nie znajduje się on na liście należy wtedy ponownie uruchomić repozytorium (błąd EA)].

Szablon stworzone przez użytkownika można również przeglądać i edytować w oknie generowani dokumentacji w zakładce “Template”.

Elementy Model document i Master document posiadają wiele zaawansowanych i bardzo przydatnych funkcji, które zostaną opisane w dedykowanych artykułach.

Szablon dokumentacji (RTF Template)

Trzeci elementem niezbędnym do generowania dokumentacji jest szablon RTF (RTF Template), który stanowi definicję rozdziału dokumentu. To właśnie w nim ustalamy, jak ma wyglądać rozdział, jakie elementy mają zostać wygenerowane oraz jakie elementy chcemy zawrzeć w rozdziale. 

Lista szablonów dokumentacji jest dostępna w zakładce Configure -> “Reasurces”. W tej lokalizacji możesz przeglądać, edytować i tworzyć szablony.

W ramach Enterprise Architect zostały przygotowane systemowe szablony, które można wykorzystać do generowania dokumentacji lub na ich podstawie stworzyć własne. Tworzenie własnych szablonów od podstaw zostanie opisane w dedykowanej serii artykułów, ponieważ wymaga to większego wyjaśnienia.

Jak wygenerować dokumentację?

Jeżeli przygotowałaś już Master Document, zdefiniowałeś rozdziały i wybrałeś szablon generowania dokumentacji to możesz kliknąć F8 na elemencie <<master document>> w Project Browser. W konsoli, która zostanie wyświetlona musisz wskazać lokalizację oraz format zapisu, a także wybrać opcję Generuj (“Generate”).

W drugim podejściu (czyli generowaniu dokumentacji na podstawie pakietu) generujemy dokumentację w niemal identyczny sposób, jednak zamiast master document wskazujemy pakiet na podstawie, którego generujemy dokumentacje.

Wygenerowana dokumentacja zostanie zapisana w wskazanej przez Ciebie lokalizacji. Gdy wyskoczy Ci błąd generowania dokumentacji zweryfikuj czy prawidłowo wskazałeś lokalizację zapisu stworzonego dokumentu.

Co dalej?

Na podstawie teorii wiesz już czym jest diagram dokumentacji i znasz jego podstawowe elementy. Spróbuj zastosować teorię w praktyce. W razie pytań pisz do mnie, na pewno odpowiem na zadane pytanie.

Polecam zajrzeć do artykułu zawierającego 9 RAD jak tworzyć czytelne modele.

Kolejny artykuł będzie o stworzeniu szablonu RTF z użyciem wbudowanego narzędzia. Do zobaczenia!

• Konferencja IREB – Warszawa – 25 kwietnia 2024
• 5 źródeł wiedzy do śledzenia w 2024 roku!
• EAUG Poland 2023 Gdańsk!
• Jak stworzyć model RACI w Enterprise Architect krok po kroku
• Odkryj swoje talenty. Moje wyniki i analiza.

Bibliografia

1. Sparxsystems https://sparxsystems.com/enterprise_architect_user_guide/9.2/reporting/rtfdocuments.html [Data dostępu 20.06.2020r]
2. Sparxsystems https://sparxsystems.com/enterprise_architect_user_guide/9.2/reporting/rtfdocuments.html [Data dostępu 20.06.2020r]
3. Blog Eablogpl https://eablogpl.blogspot.com/2012/12/generowanie-raportow-enterprise-architect.html [Data dostępu 20.05.2020r.]
4. Blog Eablogpl https://eablogpl.blogspot.com/2012/12/definicje-pojec-zwiazanych-z.html [Data dostępu 20.05.2020r.]
5. Eablogpl https://eablogpl.blogspot.com/search/label/dokumentacja [Data dostępu 20.05.2020r.]