Structuring your document

Navigation:  Creating your first document >

Structuring your document

Previous pageReturn to chapter overviewNext page

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, so it’s possible to 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 outset, things can quickly become difficult and time consuming.

Fortunately eaDocX has a number of different approaches to extracting and organising EA model data to produce the document structures we need.

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

This is by far the simplest way to use EA with eaDocX.

The very 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 keep generating sub-headings all the way down to the lowest level package:

So an EA model like this:

graphic

… 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

 

We can then tailor 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 document, with different structures, from the same model?

2.  EA Structure ≠ Document Structure

Where we have complex models, and complex document requirements, EA and eaDocX show their real power.

When two or more 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 available to us.

a)  Use relationships, not packages

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.

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.

 

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

 

graphic

 

The Package structure for these elements is:

 

graphic

 

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

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

1.0 My Project

          1.1 Components

..details of the components..

          1.2 Use Cases

..details of the use cases...

          1.3 Requirements

..details of the requirements...

 

 

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):

1.0 My Project

          1.1 Component 1

...details of Component 1...

 

             1.1.1 Use Cases implemented by this component

                1.1.1.1 Use Case 1

                       ..details of Use Case 1...

                       1.1.1.1.1Requirements for this use case

                              1.1.1.1.1.1 Requirement 1

                                   ..details of requirement 1...

              1.1.1.2 Use Case 2

                       1.1.1.2.1Requirements for this use case

                                   1.1.1.2.1.1 Requirement 2

                                   ..details of requirement 2...

         1.2 Component 2

            1.2.1 Use Cases implemented by this component

              1.2.1.1 Use Case 3

                      1.2.1.1.1Requirements for this use case

                                   ...

 

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, going back to the initial diagram, 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:

graphic                  

 

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

 

graphic

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.

 

This approach works very well when we can ensure that everyone who is working on the model is following 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 which doesn’t use these relationships consistently (they probably aren’t your models…) but we 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 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:

graphic

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:

graphic

Our ad-hoc diagram looks like this:

graphic

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.

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

 

3.      Summary

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.  In this way, eaDocX makes it easy for a shared EA model to become the single version of the truth for large, complex projects.