Navigation:  Creating your first document > Structuring your document

The main challenge we face when using EA models to generate documents is that it's sometimes hard to predict what documents we might need.

If we're lucky, our EA models are used to produce just a single document, and we can make the structure of the EA model follow the structure of our document.  But if we have multiple documents to create - or the content and structure of our document is not clear at the start - things can quickly become confusing and time-consuming.

Fortunately, eaDocX has many different approaches to extracting and organizing EA model data to produce the document structures we need.

•The simplest is where the EA Structure can be used for the document structure

Other structuring techniques:

•Use Relationships to determine the structure.

•Use ad-hoc diagrams

•Add an Element Report or a Matrix Report

•Add a section based on an EA RTF Model Document or Master Document.

•Add a section based on a Model View Favorites folder.

 

1.      EA Structure = Document Structure

Using the EA Structure in your document is by far the simplest way to use EA with eaDocX.

The simplest document just has a single eaDocX Section, containing a single package. The resulting document will then create Word headings for each of the child packages and generate sub-headings down to the lowest level package:

So an EA model like this:

… becomes a Word Document like this:

We might then customize the order in which the packages & elements appear in EA to match the sequence we want in the document.  thereby change the EA package structure to fit the document.

This approach can also be refined in different ways:

•Unwanted packages, elements, or diagrams can be excluded from the document.

•Unwanted element types or individual element stereotypes can be excluded.

•Additional sections can be added so that the document contains information from several parts of the model.

The approach works well for situations where the document structure and model structure can be made the same. But what about when our models become more complex, and we need to produce a range of documents, with different structures, from the same model?

See also: Known issues with EA and eaDocX

2.  EA Structure ≠ Document Structure

When documents need to have different structures but use the same EA data, we can't use just EA packages to determine the structure of all the documents.

Fortunately, EA and eaDocX have several solutions:

a)  Use relationships, not packages

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

You will usually 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.

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

 

The Package structure for these elements is:

 

 

This is a standard way to store these elements in EA.

The ‘normal’ structure (i.e. eaDocX following EA structure) would be:

 

 

However, an alternate structure for our document could be to describe each Component, including all its use cases and all the associated Requirements for each use case, and do this for all the components (i.e. to look like this):

 

 

We could make the EA structure follow this pattern, but that might stop some other document from printing correctly. Or, we might not be allowed to make these kinds of changes.

Instead, we can use 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 related to them via a' Realization' connection:

                 

 

Similarly, we can tell Use Cases to print all their related 'Requirement' elements connected with a 'Realization' relationship:

 

We can do this with high precision by having different formatting for each element type & stereotype. We can be 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.

This approach works very well when we can ensure that everyone working on the model follows the same modeling standards. (If they aren't, eaDocX documents will soon show where there are model inconsistencies.)  But what if we have a model that doesn't use these relationships consistently (they probably aren't your models) but still need to produce a great-looking document?

b)  The Ad-hoc Diagram Approach

Wouldn't it be great if there was a way to create a document by 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. Our documents seem to typically 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, w '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.e've called it 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 a 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:

This technique provides a way of quickly creating a document from information found anywhere in your model, using a whole variety of EA elements.

You can refine this even further by selecting the visibility of attributes and operations/methods in your class diagrams, and eaDocX will print only those attributes and operations, which are shown in the diagram.

See Selecting Attributes and Operations for more details.

4. Using Model Views

•Add a section based on a Model View Favorites folder.

5.      Summary

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

In this way, eaDocX makes it easy for a shared EA model to become the single version of the truth for large, complex projects.