Zkušenosti s reporty ve Sparx EA na středně velkém projektu

1. Zkušenosti s generováním
reportů
Jaromír Kuželka
27.6.2018

2. O čem si budeme povídat?
• Jak jsem dokumentoval s EA na středně velkém IT projektu

3. Motivace a kontext
• Středně velký IT projekt dodávaný interně
• Moje role v projektu
• IT analytik
• Mí odběratelé
• Zadavatel / účetní metodik
• Vývojář

4. Cíle
• Vývojářům dodávat jednoznačné a pochopitelné zadání k vývoji
• Rozumět si se zadavatelem
• Identifikovat přírůstky funkčností k jednotlivým milníkům projektu
• Dlouhodobá konzistence formy a struktury

5. Hlavní problémy
• Informační hustota a relevance pro čtenáře
• Čtenář dostane jen to co ho zajímá, dokument bude kompaktní
• Štábní kultura
• Vzhled generované dokumentace odpovídající firemním šablonám
• Vyznačování změn
• Čtenář vidí co se změnilo

6. Řešení
• Generování dokumentace pomocí Master document
• Ruční postprocessing ve Wordu

7. Informační hustota
• Potřebujeme být schopní dostat z modelu jen informace
zajímavé pro danou roli
• Co nejvíce informací na jednotku plochy
Řešení
• Model strukturovat na nejvyšší úrovni po disciplínách a dále dle řešených
problematik
• Dokumentace rozdělit per odběratel
• Specializované šablony pro jednotlivé problematiky, obsahující jen použité
atributy
• Vyvarovat se prázdných elementů – filtrace v EA

8. Vzhled dle firemních šablon
• Titulní stránka + obsah
• Obsah se generuje do plné hloubky, je rozsáhlý
• Řešení: Omezení zobrazených úrovní ve Wordu
• Konzistentní číslování
• Aby jednotlivé sekce nezačínaly opět od 1, trochu magie
• Řešení: správné použití List override
• Styly
• Editor v EA je zastaralý
• Řešení: Externí styl importovaný do Wordu

9. Vyznačování změn
• Stručný popis změn v EA
• Detailní porovnání změn ve Wordu

10. Cyklus přípravy dokumentace
• Na začátku
• Připravit stylový předpis v EA (včetně nastavení číslování pomocí List override)
• Připravit šablony + titulní stránku v EA
• Připravit externí stylový předpis pro Word
• Při tvorbě modelu
• Popisovat změny do Introduction
• Po zpracování
• Vygenerovat

11. Cyklus přípravy dokumentace
Po vygenerování
• Postporcessing ve Wordu
• Uložit dokument bez podpory zpětné kompatibility
• Nastavit mu název s aktuální verzí
• Nastavit nižní úroveň zanoření obsahu
• Načíst externí styl
• Resetovat ručně potřebné styly
• Provést porovnání s vhodnou předchozí verzí
• Postprocessing v EA
• Zazálohovat model ve vygenerované verzi (např. baseline)
• Zvýšit verzi v tagged value
• Připravit nový řádek do Introduction

12. Cyklus přípravy dokumentace
A to nejdůležitější:
• Uložit dokument na všem dostupné místo
• Informovat všechny odběratele, že mají k dispozici novou dokumentaci
• Předat odběratelům dokumentaci

13. … a můžeme jet na novo další iteraci
Díky za pozornost!

14. Back up

16. Filosofická část

17. Cíle
• Dokumentace je čitelná odběratelem
• Dlouhodobě udržovatelná
• Minimum ruční práce se samotnou dokumentací
• Solidní vzhled, v souladu s korporátními šablonami

18. Proč generovat dokumentaci
• Odběratelé neumí číst přímo v EA nebo jej nemají
• nebo se nedostanou do modelu
• Model je vždy „napřed“ – neodráží naposled předaný stav
• Dokument ukazuje jen informace které chceme předat
• Lze optimalizovat pro každého čtenáře
• Dokument lze archivovat i po skončení fungování modelu

19. Použitelnost pro čtenáře
• Chceme aby čtenář dokumentaci používal
• Dáme mu jen to co potřebuje
• Vůči jeho roli
• Vůči milníku v projektu
• Strukturujeme dle jeho potřeb a vnímání problému
• Informace z modelu využijí čtenáři v různých rolích
• Nutnost více výstupů/pohledů na model

20. Použitelnost pro čtenáře
• Obsah
• Samotné diagramy nestačí
• U všeho popisy
• Popsat význam a účel (proč to je)
• Slovně popsat co je na diagramu
• U packages (=kapitol) úvodní text
• Jednoduchý popis – Note
• Použitelné křížové odkazy
• Pro komplikovanější popisy - Linked document
• Systém v diagramech
• Pod package přehledový diagram (typ Package)
• Pod elementem diagram s detaily či vazbami daného elementu na okolí

21. Použitelnost pro čtenáře
• Strukturování obsahu
• Model strukturovat na nejvyšší úrovni po odběratelích a dále dle řešených
problematik
• Dokumentaci rozdělit per odběratel
• Specializované šablony pro jednotlivé problematiky

22. Verzování a dlouhodobá udržitelnost
• Chci být schopný
• držet dlouhodobě konstantní strukturu dokumentace
• umět rozlišit co se změnilo od posledního vydání, optimálně mezi libovolnými
dvěma milníky v projektu
• čtenář by měl být schopný poznat k jakému milníku se dokument vztahuje

23. Verzování
• Čísla verzí
• Hlavní verze sladěná s projektovými milníky (sprint, release, …)
• Subverze dle vydání v daném milníku
• Konzistentní pojmenování dokumentů, včetně verze
• Pozn:
• Vytvořit novou verzi nestačí
• Je třeba informovat čtenáře o tom, že to nastalo, popsat stručně důvody
(přehled změn) a umístit dokument na místo dostupné čtenářům
• Optimálně vše se čtenáři projít formou proezentace

24. Minimalizace práce s dokumentací
• Krátká doba pro získání dokumentu
• Opakovaná manuální činnost je otravná
• Zvyšuje riziko zavlečení chyby
• Zvyšuje zastupitelnost tvůrců dokumentace
• Možnost rychlé opravy a nasazení „než si toho někdo všimne“

25. Praktická část

26. Verzování - EA
• V master documentu je číslo verze (tagged value)
• Objeví se uvnitř dokumentu
• V package s model dokumentem je element s linked dokumentem,
kam píšu slovně změny v dané verzi

27. Verzování - postprocessing
• Ke každé verzi vznikne i porovnání s vhodnou předchozí verzí
• V názvu dokumentu uvedeno jako „diff“ + číslo porovnávané verze
• Porovnání změn ve Wordu
• Pozor: Word označuje všechny obrázky jako změněné.
• Výhoda použití popisů diagramů - v textu jsou změny poznat

28. Automatizované kroky
• Dokumenty pro jednotlivé odběratele
• Master document v EA
• Mapování na hlavní sekce modelu
• Šablony pro jednotlivé části dokumentace
• V EA (styly částečně mimo EA)

29. Ruční kroky
• Číslování verzí v EA a v názvu vygenerovaného souboru
• Přehled změn v dané verzi
• Porovnání s předchozí verzí

30. Postprocessing ve Wordu
• Dokument přeuložit bez zachování zpětné kompatibility
• Výrazně sníží velikost souboru (cca 1:10)
• Upravit úrovně zanoření v obsahu
• Pomocí Toggle field codes

31. Solidní vzhled dokumentace
• EA má práci se styly uživatelsky nepříjemnou
• Hlavní problémy
• Jakékoli složitější formátování než Bold, Italic a barva textu
• Číslování nadpisů
• Pořadí generovaných informací na úrovni elementu

32. Číslování nadpisů
• Je potřeba dodržet konzistenci v použitém List override u nadpisů a
dále použít ve všech šablonách nadpisy z jednoho stylového předpisu.
• Resources
• Stylesheets
• My stylesheet
• Vytvořit List: My headings
• Vytvořit List override pro My headings
• Nastavit List numbering (použít vytvořený List override)
• User templates
• My templates
• Template 1 (Update styles: My stylesheet, použít styly s nadpisy)
• Template 2 (Update styles: My stylesheet, použít styly s nadpisy)

33. Stylové předpisy
• Správa stylů přímo v EA je vhodná jen pro základní styly
• Co se dělá obtížně:
• Předsazení nadpisu vlevo
• Barvy čísel či odrážek
• Využití místa až do okrajů

34. Stylové předpisy
• Řešení
• Použít externí styly ve Wordu
• Princip:
• Vytvoř soubor DOTX obsahující definice stylů s odpovídajícími názvy jako máš
v EA stylesheetu
• Povol si ve Wordu toolbar Developer
• U vygenerovaného dokumentu proveď načtení externího stylu
• Proveď pročištění stylů z EA a přepsání styly ve Wordu pomocí Select all ->
Clear all -> aplikace stylu