Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

Zkušenosti s generováním reportů

101 views

Published on

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

  • Be the first to comment

  • Be the first to like this

Zkušenosti s generováním reportů

  1. 1. Zkušenosti s generováním reportů Jaromír Kuželka 27.6.2018
  2. 2. O čem si budeme povídat? • Jak jsem dokumentoval s EA na středně velkém IT projektu
  3. 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. 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. 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. 6. Řešení • Generování dokumentace pomocí Master document • Ruční postprocessing ve Wordu
  7. 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. 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. 9. Vyznačování změn • Stručný popis změn v EA • Detailní porovnání změn ve Wordu
  10. 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. 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. 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. 13. … a můžeme jet na novo další iteraci Díky za pozornost!
  14. 14. Back up
  15. 15. Filosofická část
  16. 16. 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
  17. 17. 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
  18. 18. 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
  19. 19. 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í
  20. 20. 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
  21. 21. 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
  22. 22. 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
  23. 23. 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“
  24. 24. Praktická část
  25. 25. 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
  26. 26. 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
  27. 27. 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)
  28. 28. 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í
  29. 29. 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
  30. 30. 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
  31. 31. Čí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)
  32. 32. 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ů
  33. 33. 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

×