Structuring your Document

eaDocX provides several ways of extracting data from your EA model; by following the EA package structure, by using relationships or by creating ad-hoc diagrams.  This means that it is straightforward to produce many different documents, each with its own structure, from a single model.  

 

By following the EA package structure:

When we designed eaDocX, our main goal was to make generating documents quick and simple. And the simplest way to use eaDocX and EA is to make the structure of your document follow the structure of your model. To do this, find the content in the EA Project Browser which you want to include in your document, and choose the highest-level package - even if that package contains information you don't want to print.

Add that to an eaDocX section in your document.

eaDocX will then create headings for each package, going down the package tree, and creating lower-level Word headings.

So an EA model like this:

… becomes a Word Document like this:

1.  Analysis
1.1       Use Case Model
1.1.1       Actors
1.1.1.1   Administrator
1.1.1.2   Inexperienced Customer
1.1.1.3   …
 
1.1.2 Use Cases
                              ….
1.2 Business process Model
 
 
You can then remove any EA information which you don't want, by excluding the package, element or diagram in the eaDocX 'Preview' page.

These exclusions will be added to the eaDocX Profile for your document, so next time you re-generate the document, those exclusions will still apply. The Preview pane will show what is included and excluded in the document, so you can change your mind later.

This approach - adding the highest-level EA package, then excluding what's not needed - is the best way to keep your documents and model up to date. As you add more sub-packages in EA, they will get picked-up by eaDocX next time you re-generate the document.

 

By using relationships:

In this approach, rather than using the package/sub-package relationships which are implicit in the EA package structure, we use the relationships which exist between elements to provide the structure.

For example, suppose we have a model with Components, Use Cases and Requirements, linked like this:

 
If eaDocX could only follow the EA structure, in the EA Package Browser we’d have to drag the Use Cases to be children of the Components, and the requirements to be children of the Use Cases. This would be fine for our document, but make a mess of any other documents which relied on the old structure.  As a result we’d have to restructure our model for each document we wanted to produce.
 
Instead, our elements already know who is related to whom, so we can use those relationships, rather than the package structure, to determine the structure of our document.
 
When we print Component elements, we can configure them to print all the “Use case” elements which are related to them via a ’Realization’ connection:
 
 
Similarly, we can tell Use Cases to print all their related ‘Requirement’ elements, which are connected with a ‘Realization’ relationship:
 
 
We can do this with great precision, by having different formatting for each element type & stereotype, being very specific about which relationships we want to navigate, using the relationship type (Dependency, Realization, Association etc) and even the name & stereotype of those relationships.
 
Usually, you will want to specify that the related data is a simple attribute (INLINE or as a column in a table) or as a separate relationship table.  However, by adding a Relationship Element to the formatting of another element, the related element will print out in whatever way the Profile says it should print. This may seem like an unnecessary option, but it allows you to print your document entirely based on the relationships between elements, and not on the package structure.
 
 
 
By creating ad-hoc diagrams:
 
Wouldn’t it be great if there was a way to create a document by just dropping any element from anywhere in the model into our document? We could do this by creating a new eaDocX section in the document for each element or package we need, but that would quickly get unmanageable. (Incidentally, our documents seem typically to have 3 to 8 sections, including document information and glossary sections.)
 
There is one more eaDocX trick to create the perfect document.
 
Create a new diagram somewhere in your model. We generally use a separate part of the model for this, called something like ‘Ad-Hoc Diagrams’. Then drag & drop the elements & packages you want to document into this diagram.  Add your diagram, or the package which contains it, into an eaDocX section in your document, and configure the diagram to print in ‘Contents, no diagram’ style. This tells eaDocX that it’s not the diagram you want to print, just the contents of it.
 
For example, in the EA Package Browser we have:
 
 
We included the “Ad Hoc Diagrams” package in its own section in our document, and selected ‘Contents, no diagram’ for the ‘Stuff for the meeting on Tuesday’ diagram. In the eaDocX Preview page, this looks like:
 
 
Our ad-hoc diagram looks like this:
 
 
When printing diagrams like these, eaDocX will use the formatting options for each of the elements in the diagram. In this example, Actor elements print inline and Issues print in tables. (Packages, by default, always print inline.)  So the resulting document Section looks like this:
 
3.      Tuesday review meeting
 
Issue                 Description
this is going to be a problem
 
1.1. A2
Actor 2 represents…
 
1.2. Package11
 
          1.1.1. A1
                    Actor 1 represents….
 
          1.1.2. Package111
                     This is the description of Package 111
 
This technique provides a way of quickly creating a document from information found anywhere in your model, using a whole variety of EA elements.
 
 
Using these different ways to structure documents, eaDocX makes it easy for a shared EA model to become the single version of the truth for large, complex projects.