Try RepoDoc, a new way of documenting your repository.

It’s easy to use, powerful and we offer it for free to anyone willing to test or help.

What is RepoDoc?

A document generator add-in for Enterprise Architect.

What makes it special?

• uses Liquid templates that are easy to create, modify and maintain,
• offers flexible repository filtering capabilities,
• makes non-linear document generation possible,
• supports a wide range of document formats including, but not limited to, HTML, LaTeX, PDF, Markdown, AsciiDoc, CSV, XML or JSON files, SVG, source codes in different languages,
• contains a built-in post processor.

How can you help?

• try it out and submit your wishes for a must/nice to have functionality,
• write a new interesting template or let us know what kind of template would you need.

What you can achieve?

Here are few examples of documents, generated with RepoDoc. Find more at repodoc.archimetes.com.

UML model overview (HTML)

Requirements catalogue (LaTeX)

Dependency graphs (DOT/Graphviz)

Dependencies between UML elements.

Dependencies between Archimate elements.

Class diagram overview (AsciiDoc)

Package list (JSON)

About

RepoDoc is a document generator for Enterprise Architect able to produce a variety of document formats using templates written in any text editor.

How it works

RepoDoc takes a document template and a starting package as input. It outputs a plain text document together with repository artifacts specified in the template and taken from the repository. An optional profile may be specified to instruct RepoDoc to post-process the document with a third party software (like Asciidoctor or Pandoc).

RepoDoc uses plain text templates and an easy to learn Liquid template language. This allows to output a broad range of different plain text formats like CSV, XML or JSON, but also to post-process the result in various third party backends to produce an office document like DOCX. It also offers new possibilities when iterating repository like multiple iterations, custom loops, conditional expressions and more.

How to use

1. Download and install latest RepoDoc bundle.
2. Start Enterprise Architect and open your project.
3. Select RepoDoc from the Specialize ribbon and open its control panel.
4. Click Generate.
5. Click View.

Features

✅ Markup languages

Use your favorite markup language like Markdown or AsciiDoc to prepare your document then convert the output to a HTML or DOCX with a single click.

✅ Conditional expressions

Document only elements you need and when you need them. Write logical conditions based on name, type or number of child elements. No more empty sections or tables in the output document.

{%- for element in package.elements -%}
  {%- if element.type == "Actor" -%}
    Documenting actor name {{ element.name }}
    and actor notes {% if element.notes != "" %}{{ element.notes }}{% endif %}
    (but only if non empty).
  {%- endif -%}
{%- endfor -%}

✅ Multiple iterations

Iterate and document your repository items multiple times. Create requirements section first and then add a use case section. Everything aligned in a single document.

Now I'm documenting only actors.
{%- for element in package.elements -%}
  {%- if element.type == "Actor" -%}
    ...
  {%- endif -%}
{%- endfor -%}
And now I'm documenting only use cases.
{%- for element in package.elements -%}
  {%- if element.type == "UseCase" -%}
    ...
  {%- endif -%}
{%- endfor -%}

✅ Output redirection

Output images or artifacts to individual files. Export data in different formats to multiple files.

✅ Relationships & analysis

Walk through the connections for elements and diagram objects and document important ones. Analyze and document impacts with recursive templates.

✅ Version control

RepoDoc uses plain text Liquid templates that are ideal for version control system. Track changes in your templates and tag them easily.

Want more?

Select another template or write quickly your own with an easy to learn language. Find out more about RepoDoc at repodoc.archimetes.com.

Even though Agile promised us “working software over comprehensive documentation” in its Manifesto there are still highly regulated industries, such as banking, healthcare, insurance and government administration (to name just few), where IT systems must be properly documented. Even when your development team is agile, proper documentation is still vital for complex solutions. Quite frankly, most of the IT systems developed in-house are complex and closed – they are developed by handful of people who know them inside out but no one else in the organization knows how they work – just image what would happen if they are gone?

Usually, documentation is written by Business Analysts, System Analysts and Architects as a text documents in Microsoft Word with a set of UML diagrams exported from some modeling tool. It is a terrible but extremely popular way of documenting IT systems (for many reasons which are not in the scope of this article). Fortunately, this mundane and unproductive task can be easily automated even for complex and robust templates.

From this article you will learn how to use Sparx Enterprise Architect to created advanced template for Use Case Specification that can be easily used for documentation generation by any member of your team.

How to create extensive Use Case Specification template in Enterprise Architect?

Let’s start from the repository structure. I have following, very simple setup of the repository in Enterprise Architect (left picture).  This setup is focused on the Business Analysis and not System Architecture but this does not matter in context do document generation.

The important thing is that the model in Project Browser is presented in the tree-like structure and this approach is also passed on the Document Generation functionality (internal part of EA responsible for report generation). Which means that we can generate documentation for whole model (staring from root node called ‘Model’ in our example) or just one branch, such as Requirements or UseCases.

When we expand one of the branches of the tree, let’s say UseCases we can see what’s located in that package (right picture).

The problem is, that Document Generator can access only elements within selected branch. So in our case it has access only to contents of the Front Office package. It can not move up in the tree structure or “jump” to another branch. Well, at least simple Document template can not.

But what to do if we want to generate UseCase Specification document that also includes Requirements realized by each UseCase and Mockups? We need to access information from different “part” of the model, but stay in the context of UseCases – which are the main subject of UseCase Specification document.

Well, there are many solutions. The first, obvious, one is to reorganize the structure of the project repository, so everything is “under” UseCases package. This is a terrible solution and don’t do it ever, never! Just think what would happen if you would like to document Requirements or Processes – you would have to change the structure for each Template.

To solve this problem, Sparx engineers added Virtual Documents functionality. This is extremely powerful method of generating documentation which allows us to build one big document out of many parts. Each part has dedicated role of documenting particular concept. So, for example, we would have one part for Requirements, one for UseCases, one for Actors, one for Mockups and so on. In my opinion this functionality works best for huge documents, such as Software Architecture Document (SAD) or Business Requirements Document (BRD), which present concepts holistically and are usually created once in a while. On a daily basis we never need documentation that covers whole scope of the solution (IT system). Generating new version of BRD and handling it to Development team every time one Requirement was changed is not useful. On a daily basis more flexible and fine-grained documentation is needed. Unfortunately, setting up Virtual Documents for each smaller case is mundane and time consuming task.

This brings us to the second solution, instead of creating Virtual Documents manually, we may generate them and then use them to generate documentation. This is two step, semi-automatic solution proposed by Geert Bellekens in his article Generate complex documents from Enterprise Architect with a two-step semi-automated approach. It works very well, however it may be quite hard to comprehend for ordinary EA users. After all, not every Analyst and Architect must be Enterprise Architect super user at the same time.

Now, I’d like to present the third solution. I created it quite recently as it uses new feature added lately to Sparx Enterprise Architect in version 12.1.1224. It allows to generate documentation which includes information from different “project branches” by simply pressing F8 button (Generate Documentation key-shortcut).

What I needed was a template that would generate documentation with following parts:

1. UML Use Case diagram for each Use case package
2. Detailed information about each Use Case, including
   1. Description (goal, pre-conditions, post-conditions)
   2. Scenarios: main scenario and all alternative scenarios
   3. UML Activity diagram presenting visually all scenarios
   4. List of requirements realized by the Use Case (trace relationship between Use Case and Requirement)
   5. Mockup diagrams or other images associated with a Use Case

Below there is a picture that collates Table of Contents (ToC) of generated document and Project Structure (inside Enterprise Architect).

Firstly, it is worth to say that by default Document Generator evaluates only the selected package and its sub-packages. In our case that would be all the elements in the red dashed-line box. The realized requirements has been found by SQL script, and Mockups via Document Script (listings of used scripts are included below).

How this was achieved?

The UseCase Specification template has been created with few additional fragments. Fragments encapsulate some specific part of the template and can be reused among many templates. Each fragment is included in the particular place of the main template, they are highlighted in red.

The first fragment is quite boring from template designer perspective. It’s purpose is to include the UML Activity Diagram of each Use Case into the documentation. Please notice that those Activity Diagrams are automatically generated by Enterprise Architect from Structure Scenarios of each Use Case which is a feature of EA that I absolutely love, but I digress.

SQL Template Fragment

The “Fragment UseCase realized Requirements” is responsible for presenting list of requirements that are realized by the particular UseCase. It uses SQL to retrieve information about requirements from EA’s internal database and displays them in a table.

Because information is retrieved by a SQL query we need to embody template in a custom tag and refer directly to the results of the query (objectname, objectstatus, lastmodification, idAlias).

On the line 5 there is #OBJECTID# token. It is Enterprise Architect parameter that during generation of documentation is replaced by the ID of currently processed element. The value of this ID is passed from the main template, therefore it always (in our case) refers to an element of type UseCase. The rest is self-explanatory.

Document Script Template Fragment

It is a type of template that executes a script in order to retrieve data from a model. However, I used it in a little bit more advanced way. The “Fragment Mockup Diagram” uses Document Script to retrieve information from the model and generate RTF document in memory, which is later included in the generated documentation. It is somewhat complex and definitely not straightforward setup which consists of the following elements:

• “Fragment Mockup Diagram” – a template which is included in our main template and is used to execute a Document Script
• MockupDiagram script – it is a JScript executed when the “Fragment Mockup Diagram” is being evaluated
• MockupTemplate – a template used to generate RTF document from the script

As it was said, the “Fragment Mockup Diagram” is just used to execute the MockupDiagram script. To setup it we need to go into Document Options of the template, then Custom Query tab and select Document Script. From the dropdown menu that appears select MockupDiagram (of course you need to create it first – I will explain how in a moment). I think this images illustrates this better.

The main(#OBJECTID#); code executes the main function of the MockupDiagram script, with ID of the currently processed object, in the same way as it was for SQL query explained above.

Note: For some reason it is necessary to include empty custom tag in this Document Script fragment template. Otherwise, generated documentation does not contain this part of documentation generated by Document Script. I think this is a bug in EA, definitely it’s not described in the documentation.

To create a script in Enterprise Architect select Tools -> Scripting from main menu. In the Scripting window create new Normal Group and add New JScript. The source of the MockupScript is presented on the listing below.

This code is not that complex, mostly it’s simple JavaScript, however, few lines deserve some additional comments.

• At line 4 the name of the template is defined. This template will be used to generate content for the “Fragment Mockup Diagram”, which was left empty.
• Line 28 – DocumentGenerator.GetDocumentAsRTF(); – this is a builtin function that does all the magic. It generates RTF document in the memory. Later, this RTF document is injected into the main UseCase Specification template.  More information can be found in EA help file here DocumentGenerator Class.
• Lines 49 & 54 – they define condition describing how to find mockups for our UseCase. The assumption here is that in every Package to which UseCase is traced contains Mockups. This gives us easy of use while working with the model
• Line 66 – for each Package we generate part of the RTF document using template defined in line 4.

The MockupTemplate is quite simple template that generates part of documentation from data retrieved by MockupDiagram JScript.

It displays package description (Notes) and includes Mockup Diagrams created in Enterprise Architect or in other tools, such as Balsamiq Mockups,  placed on the diagram as images.

Those are all components needed to generate documentation. All the rest is present in the model.

How to use it?

We use our template setup in pretty straightforward way. In Project Browser just select UseCases package and click F8 key. Configure the Generate Documentation as presented on the picture below.

Click generate. After generation is finished just click View to see generated documentation. Below is embedded output PDF file you can also download it from here UseCase Specification PDF.

What was achieved?

The possibility to have complex template that is extremely easy to use (jest press F8 key) without sacrificing the repository structure and use of more advanced documentation techniques which may be overwhelming for some EA users. Also the repository model and template promote use of traceability. Whenever there is new Requirement or new Mockup we can add them to the model
and trace to the particular UseCase. Template will pick up automatically new elements added and they will be included in newly generated documentation. Therefor, you can prepare similar template for your team of designers (Analysts, Architects) and they don’t need to worry about the template while adding or modifying elements.

Free download

The sample EAP project file can be downloaded here: EAP UseCaseDocumentationExample.  The EAP file contains full model, all examples, templates and scripts. To see and edit templates just go to Resources window (Alt+6). To generate document for yourself just go to How to use it? paragraph above and follow the instructions.

 You’re free to modify it and use it for commercial purpose. Any comment or simple “Thank you” will be highly appreciated :-)

This article was originally posted on my blog http://zubkiewicz.com/

Introduction

In order to provide a consistent look-and-feel to documents (RTF/DOCX/PDF) produced from Sparx Systems Enterprise Architect, Sparx Systems provided the facility of a Style sheet so that when applied, the styles defined in the style sheet override the corresponding styles used within the document template(s).

A style sheet is selected when a document is to be generated using either:

• An artefact selected in the Project Browser such as a package.

• A Master Document.

The main challenge faced by EA users is the creation of the style sheet, this tutorial provides you with the techniques for the creation and use of a style sheet.

Please see the attached tutorial for full details of this process.

Hippo Software's recently extended workshops are designed to expand and enhance delegates' knowledge of Enterprise Architect:

•           EA Document Workshop – create custom document templates

•           EA Excel Data Transfer Workshop – easily share requirements or other data

•           EA Scripting Workshop – facilitate repetitive or complex tasks on models

•           EA Profiles Workshop – define custom diagrams, toolboxes, elements and relationships

For more information, please visit the Hippo Software website below:

http://www.hippo-software.co.uk/pages/EA.htm