{"id":225,"date":"2020-07-07T15:25:07","date_gmt":"2020-07-07T13:25:07","guid":{"rendered":"http:\/\/www.analizatozalezy.pl\/?p=225"},"modified":"2023-02-22T16:51:01","modified_gmt":"2023-02-22T14:51:01","slug":"generowanie-dokumentacji-w-ea-podstawy","status":"publish","type":"post","link":"https:\/\/www.analizatozalezy.pl\/index.php\/2020\/07\/07\/generowanie-dokumentacji-w-ea-podstawy\/","title":{"rendered":"Generowanie Dokumentacji w Enterprise Architect – podstawy"},"content":{"rendered":"\n

Rozpoczynaj\u0105c moj\u0105 prac\u0119 z Enterprise Architect, mia\u0142em wra\u017cenie \u017ce stanowi on jedynie narz\u0119dzie do rysowania diagram\u00f3w. Moje zdanie zmieni\u0142o si\u0119, gdy odkry\u0142em pe\u0142ne mo\u017cliwo\u015bci tego narz\u0119dzia. Generowanie dokumentacji na podstawie modeli analitycznych, tworzenie z\u0142o\u017conych i powi\u0105zanych relacjami modeli oraz wiele innych. Dzisiejszy wpis o podstawach generowania dokumentacji poka\u017ce Ci jak na podstawie modelu generowa\u0107 dokumentacj\u0119 WORD (a tak\u017ce PDF i RTF). <\/p>\n\n\n\n

Dlaczego si\u0119 tego nauczy\u0142em<\/strong><\/h2>\n\n\n\n

Zacznijmy od podstaw. Jako analityk, jak wielu zacz\u0105\u0142em swoj\u0105 prac\u0119 od tworzenia dokumentacji w Word, ze wzgl\u0119du na \u0142atwo\u015b\u0107 obs\u0142ugi oraz dost\u0119pno\u015b\u0107. Przy pewnym projekcie na 2 dni przed oddaniem ko\u0144cowej wersji analizy do klienta „co\u015b” si\u0119 sta\u0142o z dokumentem. Prawdopodobnie uszkodzi\u0142y si\u0119 odno\u015bniki, style, wklei\u0142y si\u0119 nowe rozdzia\u0142y z innych cz\u0119\u015bci dokumentu reasumuj\u0105c, totalny ba\u0142agan. Niestety dokument (kt\u00f3ry zawiera\u0142 najnowsze zmiany) musia\u0142em przekaza\u0107 do klienta w wyznaczonym terminie i nie by\u0142o mo\u017cliwo\u015bci jego zmiany.<\/p>\n\n\n

\n
\"Sterta
Rysunek : Du\u017co dokument\u00f3w<\/figcaption><\/figure><\/div>\n\n\n

Ca\u0142\u0105 noc i wi\u0119kszo\u015b\u0107 kolejnego dnia por\u00f3wnywa\u0142em poprzednie wersje z notatkami i szy\u0142em dokument na nowo. W tamtym czasie r\u00f3wnie\u017c studiowa\u0142em i w dniu oddania dokumentu mia\u0142em kolokwium. Dokument odda\u0142em w terminie, aczkolwiek kolokwium nie zaliczy\u0142em z braku czasu na nauk\u0119.( Szef zadowolony, ale dw\u00f3jka w dzienniku pozosta\u0142a.)<\/p>\n\n\n\n

Ze wzgl\u0119du na te zdarzenie zacz\u0105\u0142em szuka\u0107, czy mo\u017cna jako\u015b unikn\u0105\u0107 takiej sytuacji w przysz\u0142o\u015bci? Odpowiedzi\u0105 by\u0142o wykorzystanie narz\u0119dzia do modelowania oraz generowania dokumentacji. Ze wzgl\u0119du na cen\u0119, dost\u0119pno\u015b\u0107 i kilka innych czynnik\u00f3w wybra\u0142em Enterprise Architect. Dzi\u0119ki niemu mog\u0119 skupi\u0107 si\u0119 na modelowaniu biznesu i jego potrzeb, bez konieczno\u015bci po\u015bwi\u0119cania czasu na zarz\u0105dzanie dokumentem Word. W dodatku dostosowanie oraz generowanie dokumentacji na podstawie modelu zajmuje du\u017co mniej czasu oraz daje wi\u0119ksz\u0105 elastyczno\u015b\u0107.<\/p>\n\n\n\n

Od czego zacz\u0105\u0107 generowanie dokumentacji?<\/strong><\/h2>\n\n\n\n

Zacznij od wyboru podej\u015bcia do generowania dokumentacji i przemy\u015blenia struktury repozytorium. Kolejnym krokiem jest przygotowanie struktury dokumentu, szablon\u00f3w i pozosta\u0142ych element\u00f3w do generowania dokumentacji (o kt\u00f3rych w przysz\u0142ych artyku\u0142ach).<\/p>\n\n\n\n

Uk\u0142ad repozytorium<\/strong><\/h3>\n\n\n\n

Pierwszym krokiem, jest stworzenie modelu analitycznego w repozytorium Enterprise Architect. Model musi by\u0107 uporz\u0105dkowany i zawiera\u0107 elementy, kt\u00f3re maj\u0105 trafi\u0107 do p\u00f3\u017aniejszej dokumentacji. Naturalnym podej\u015bciem na pocz\u0105tek jest utworzenie struktury pakiet\u00f3w zgodnie z twoim szablonem dokumentu Word. Pozwoli to Tobie na generowanie dokumentacji bez znajomo\u015bci zaawansowanych funkcji.<\/p>\n\n\n

\n
\"Generowanie
Rysunek: Przyk\u0142adowa struktura repozytorium<\/figcaption><\/figure><\/div>\n\n\n

Dwa podej\u015bcia do generowania<\/strong><\/p>\n\n\n\n

Znam dwa podej\u015bcia do generowania dokumentacji. Do\u015b\u0107 znacz\u0105co si\u0119 r\u00f3\u017cni\u0105, wymagaj\u0105 innego podej\u015bcia do tworzenia szablon\u00f3w oraz maj\u0105 inny wp\u0142yw na komfort pracy z repozytorium. Podej\u015bcia te to:<\/p>\n\n\n\n

  1. Generowanie dokumentacji z u\u017cyciem diagramu dokumentacji i jego element\u00f3w.<\/li>
  2. Generowanie dokumentacji na podstawie pakietu z u\u017cyciem z\u0142o\u017conego szablonu dokumentacji (szablon RTF).<\/li><\/ol>\n\n\n\n

    Pierwsze podej\u015bcie<\/strong> zak\u0142ada skorzystanie z dedykowanego diagramu oraz element\u00f3w pozwalaj\u0105cych nam zdefiniowanie kolejnych rozdzia\u0142\u00f3w w dokumencie i przypisanie do nich szablonu RTF. Preferuj\u0119 ten spos\u00f3b tworzenia dokumentacji, poniewa\u017c pozwala na generowanie dokumentacji, bez zaawansowanej znajomo\u015bci tworzenia szablon\u00f3w. Podej\u015bcie to zostanie opisane w dalszej cz\u0119\u015bci artyku\u0142u.<\/p>\n\n\n\n

    Drugie podej\u015bcie <\/strong>zak\u0142ada stworzenie wielopoziomowego szablonu RTF z wykorzystanie fragment\u00f3w i innych element\u00f3w sk\u0142adaj\u0105cych si\u0119 na szablon RTF. W zwi\u0105zku z tym podej\u015bcie to wymaga dobrej znajomo\u015bci tworzenia szablon\u00f3w i zachowanie struktury repozytorium w niezmienionej formie. Ka\u017cda zmiana struktury dokumentu lub repozytorium wymusza zmian\u0119 szablonu dokumentacji. W dodatku ogranicza wykorzystanie pewnych funkcji dost\u0119pnych w Enterprise Architect, jak chocia\u017cby generowanie wybranego fragmentu dokumentu (skraca to czas generowania du\u017cych dokument\u00f3w).<\/p>\n\n\n\n

    Diagram dokumentacji<\/strong><\/h3>\n\n\n\n

    W ramach diagram\u00f3w Enterprise Architect stworzono dedykowany diagram \u201cModelDocument\u201d. Pozwala on na stworzenie struktury dokumentu. Diagram ten znajdziesz w lokalizacji [Diagram] UML Extended -> Model Document (Documentation dla 13,5 wersji EA i wcze\u015bniejszych).<\/p>\n\n\n

    \n
    \"Diagram
    Rysunek: Diagram dokumentacji<\/figcaption><\/figure><\/div>\n\n\n

    W ramach diagramu mamy dedykowan\u0105 list\u0119 element\u00f3w u\u017cywanych do definiowania struktury dokumentu.<\/p>\n\n\n

    \n
    \"Elementy
    Rysunek: Elementy diagramu dokumentacji<\/figcaption><\/figure><\/div>\n\n\n

    Jak widzisz element\u00f3w, kt\u00f3re mo\u017cna wykorzysta\u0107 jest du\u017co. Na potrzeby podstaw generowania dokumentacji wykorzystamy Master Document<\/strong> oraz Model Document<\/strong>.<\/p>\n\n\n\n

    Skoroszyt dokumentu<\/strong><\/h3>\n\n\n\n

    <<Master document<\/strong>>> stanowi \u201cskoroszyt\u201d w ramach, kt\u00f3rego zarz\u0105dzamy rozdzia\u0142ami, przepisujemy szablon RTF („papier projektowy” zawieraj\u0105cy numerowanie, nag\u0142\u00f3wek, stopk\u0119 itd.), wybieramy styl czcionek, ok\u0142adk\u0119, wygl\u0105d spisu tre\u015bci i wiele innych. Gdy utworzymy tego typu element powstanie dedykowany Element package na diagramie dokumentacji oraz w Project Browser. <\/p>\n\n\n

    \n
    \"Generowanie
    Rysunek: Master document<\/figcaption><\/figure><\/div>\n\n\n

    Jak widzisz w ramach pakietu <<master document>> zosta\u0142 utworzony automatycznie diagram dokumentacji („Wst\u0119pna Analiza Biznesowa”). W ramach tego diagramu (oraz pakietu) tworzymy elementy Model document<\/strong>, stanowi\u0105ce kolejne sekcje naszego dokumentu (np. „<model document> Cel projektu”).<\/p>\n\n\n\n

    Rozdzia\u0142y dokumentu<\/strong><\/p>\n\n\n\n

    <<Model document<\/strong>>> to element s\u0142u\u017c\u0105cy do zdefiniowania sekcji dokumentu. Sekcje dokumentu tworzymy poprzez przypisanie do atrybut\u00f3w wybranych pakiet\u00f3w z Project Browser (poprzez przeci\u0105gniecie wybranego pakietu z Project Browse na obraz Model Document na diagramie). <\/p>\n\n\n

    \n
    \"Generowanie
    Rysunek: Model document<\/figcaption><\/figure><\/div>\n\n\n

    Gdy dodamy pakiety kolejny krokiem jest dobieranie odpowiedniego szablonu RTF <\/strong>(RTF Template)(Uwaga gdy nie wybierzesz szablonu zostanie przypisany domy\u015blny szablon „Model Report”). Szablon RTF to schemat, kt\u00f3ry pozwoli na wygenerowanie poszczeg\u00f3lnych sekcji dokumentu zgodnie z za\u0142o\u017conym standardem graficznym oraz spodziewanymi opisami. Wykorzysta\u0107 tutaj mo\u017cna wbudowane lub utworzone samodzielnie szablony RTF. Wybranie szablonu mo\u017cna zrealizowa\u0107 dla elementu Model document w oknie Properties -> Tags -> RTFTemplate -> Wyb\u00f3r szablonu z listy. [Czasami po utworzeniu szablonu nie znajduje si\u0119 on na li\u015bcie nale\u017cy wtedy ponownie uruchomi\u0107 repozytorium (b\u0142\u0105d EA)].<\/p>\n\n\n

    \n
    \"Generowanie
    Rysunek: Model document – przypisanie szablonu RTF<\/figcaption><\/figure><\/div>\n\n\n

    Szablon stworzone przez u\u017cytkownika mo\u017cna r\u00f3wnie\u017c przegl\u0105da\u0107 i edytowa\u0107 w oknie generowani dokumentacji w zak\u0142adce „Template”.<\/p>\n\n\n

    \n
    \"\"
    Rysunek: Okno generowania dokumentacji zak\u0142adka Template. (EAv16)<\/figcaption><\/figure><\/div>\n\n\n

    Elementy Model<\/strong> document<\/strong> i Master document<\/strong> posiadaj\u0105 wiele zaawansowanych i bardzo przydatnych funkcji, kt\u00f3re zostan\u0105 opisane w dedykowanych artyku\u0142ach.<\/p>\n\n\n\n

    Szablon dokumentacji (RTF Template)<\/h3>\n\n\n\n

    Trzeci elementem niezb\u0119dnym do generowania dokumentacji jest szablon RTF (RTF Template), kt\u00f3ry stanowi definicj\u0119 rozdzia\u0142u dokumentu. To w\u0142a\u015bnie w nim ustalamy, jak ma wygl\u0105da\u0107 rozdzia\u0142, jakie elementy maj\u0105 zosta\u0107 wygenerowane oraz jakie elementy chcemy zawrze\u0107 w rozdziale. <\/p>\n\n\n\n

    Lista szablon\u00f3w dokumentacji jest dost\u0119pna w zak\u0142adce Configure -> \u201cReasurces\u201d. W tej lokalizacji mo\u017cesz przegl\u0105da\u0107, edytowa\u0107 i tworzy\u0107 szablony. <\/p>\n\n\n

    \n
    \"Elementy
    Rysunek: Lokalizacja szablon\u00f3w RTF<\/figcaption><\/figure><\/div>\n\n\n

    W ramach Enterprise Architect zosta\u0142y przygotowane systemowe szablony, kt\u00f3re mo\u017cna wykorzysta\u0107 do generowania dokumentacji lub na ich podstawie stworzy\u0107 w\u0142asne. Tworzenie w\u0142asnych szablon\u00f3w od podstaw zostanie opisane w dedykowanej serii artyku\u0142\u00f3w, poniewa\u017c wymaga to wi\u0119kszego wyja\u015bnienia.<\/p>\n\n\n\n

    Jak wygenerowa\u0107 dokumentacj\u0119?<\/strong><\/h3>\n\n\n\n

    Je\u017celi przygotowa\u0142a\u015b ju\u017c Master Document, zdefiniowa\u0142e\u015b rozdzia\u0142y i wybra\u0142e\u015b szablon generowania dokumentacji to mo\u017cesz klikn\u0105\u0107 F8 na elemencie <<master document>> w Project Browser. W konsoli, kt\u00f3ra zostanie wy\u015bwietlona musisz wskaza\u0107 lokalizacj\u0119 oraz format zapisu, a tak\u017ce wybra\u0107 opcj\u0119 Generuj (\u201cGenerate\u201d).<\/p>\n\n\n

    \n
    \"Generowanie
    Rysunek: Okno generowania dokumentacji<\/figcaption><\/figure><\/div>\n\n\n

    W drugim podej\u015bciu (czyli generowaniu dokumentacji na podstawie pakietu) generujemy dokumentacj\u0119 w niemal identyczny spos\u00f3b, jednak zamiast master document wskazujemy pakiet na podstawie, kt\u00f3rego generujemy dokumentacje.<\/p>\n\n\n\n

    Wygenerowana dokumentacja zostanie zapisana w wskazanej przez Ciebie lokalizacji. Gdy wyskoczy Ci b\u0142\u0105d generowania dokumentacji zweryfikuj czy prawid\u0142owo wskaza\u0142e\u015b lokalizacj\u0119 zapisu stworzonego dokumentu.<\/p>\n\n\n\n

    Co dalej?<\/strong><\/h2>\n\n\n\n

    Na podstawie teorii wiesz ju\u017c czym jest diagram dokumentacji i znasz jego podstawowe elementy. Spr\u00f3buj zastosowa\u0107 teori\u0119 w praktyce. W razie pyta\u0144 pisz do mnie, na pewno odpowiem na zadane pytanie.<\/p>\n\n\n\n

    Polecam zajrze\u0107 do artyku\u0142u zawieraj\u0105cego 9 RAD jak tworzy\u0107 czytelne modele.<\/a><\/p>\n\n\n\n

    Kolejny artyku\u0142 b\u0119dzie o stworzeniu szablonu RTF z u\u017cyciem wbudowanego narz\u0119dzia. Do zobaczenia!<\/p>\n\n\n