Document Management

EA and eaDocX make it easy to create great looking documents. Lots of them. But that creates it's own challenges.

There are lots of tasks involved with maintaining and publishing documents, apart from making sure the content is correct. This work isn't as exciting as creating the EA model, or making the document, but is needed by most organisations as part of the documentation process.

Some of those tasks are:

oKeeping track of what documents have been created from a model, and what versions of those documents exist

oUnderstanding who is involved in which document: who approves what, who owns what

oUnderstanding the relationships between documents, where one document references or depends on another

oBeing able to show where documents have changed from one version to the next.

Versioning and History

•With EA and eaDocX, we produce many more versions of document than for manually written ones. This is good, as it keep documents up-to-date, but does create a problem with looking after all the versions.

•We also needed to add information about the version to the document, at the front of the document, and often in the header as well

•As we create more versions, adding a version history, showing how the document has changed over time is useful. Something like:

Version

Date

Comments

0.0.1

1st September 2012

Initial version, for internal use only. Some Component definitions not yet complete

0.0.2

14th September 2012

Internal draft. Component defs now complete, but no detail on the Wibbles

0.1.0

28th September 2012

First external draft, for comment

 

Adding hyperlinks to take the reader straight to previous version was something we did very occasionally. With EA and  eaDocX Document Management, these can be added automatically.

See Adding Document History for how to add this information to your document, and

People and Roles

Many formal documents also have a list of people at the start of the document, saying who contributed to the document, who has reviewed it and who will sign it off. The roles vary from project-to-project, so that needs to be configurable. Where we have had to manage a family of documents - and with the flexibility of EA and eaDocX that's happening more and more - we have also found ourselves maintaining lists of people, and which document they are involved with. This is so that document can contain tables like:

Person

Role

Comments

Martin Jones, CEO

Approver

 

Clare Smart, COO

Consulted

Operations need to determine the practicality of the proposed new processes

Frank Bey, CTO

Consulted

 

 

Relationships between documents

As we develop more families of documents, rather than one single one, understanding which documents refer to which other ones is another boring task, and one which often gets overlooked as the document develops. But most documents have a section like this somewhere:

Referenced Documents

Version

Owner

GL Development Standards

2.1.0

Beth Robinson

GL Financial Handbook

1.0.0

Frank Bey

Document Status

eaDocX allows to you use two different status' for a document:

a simple status string which is attached separately to each version

•an Approval Status based on who has approved the document.

Status

Each Version of a document can have a simple status value, which is a string which you can add to the version. Each time you re-generate the document, you can change its status. This is designed to be as flexible as possible, so you might use status values of 'Draft' and 'Final', or 'Ready','Work-in-progress' and 'new'

Approval Status

This has a more exact meaning. Each document may have a number of people who are made 'Approvers' of that document. That is, they have been linked to the document with the specific rule type of 'Approver' (or the equivalent in you national language).

Each individual can then show they have approved the document, by using using the 'Approve this document' button on the Document Details page. The Approval status will be shown like:

Status

Default Text

Explanation

redCross

Unapproved

None of the approvers have approved this document

greyCross

Partially Approved

Some, but not all of he approvers have approved this document

greenTick

Approved

All of the approvers have approved this document

Changing the Approval Status.

Once someone has Approved a document, then generally that approval can't be changed. However, there may be cases where you Approve someone accidentally, and need to delete them. We deliberately don't make this simple, so that you think hard before un-approving something.

If you really do want to do this, then just drop the document version and the approver onto an EA diagram, and delete the <<hasApproved>> connector which links them

Changing the Default Text

 

Document Changes

This is another bi-product of being able to create many versions very easily. Readers of new versions need to be able to see quickly what's changed since the last version.

Our solutions to this have varied. Word has always had the 'Track Changes' feature, but eaDocX can't use that, as all the eaDocX sections in a document are replaced each time the document is re-generated. We have taken to using the Word Compare Documents feature, which compares a pair of documents, and produces a new one showing the differences. This was OK if the last version was available, but the problem was find the previous version with which to do the comparison. But now we have document versioning (see above) we can make this much simpler.

Note: In eaDocX Professional Edition, there is the 'Change Marking' feature, which highlights those element in the document which have changed, but isn't as fine-grained as the Word Compare Documents, which goes down to the tiniest changes.

 

Notes

1.eaDocX Document Management is only supported for Word 2007 and above.

2.eaDocX Document Management is not intended to be a general-purpose document configuration management & version control (CMVC) system. It's just to help you manage the eaDocX documents which you create from your EA models.

 

 

Inline Text settings

These settings control how Inline elements are printed.

They allow you control the three Word paragraph styles which are used for normal, bullet and numbered bullet text, as well as overriding the default Word heading styles ("Heading 1"..."Heading 9") with other Word paragraph styles of your own.

Note that Word Table styles which contain either spaces or diacritic characters cannot be used by eaDocX.

 

Setting

Description

Bullet List Style

Word Style used for bullets in lists:

•like this

•and this

Normal inline text style

Word Style used for simple paragraphs of text, like this.

Numbered list text style

Word Style used for numbered bullets in lists:

1.like this

2.and this

Overrides to Word Headings

Heading 1 style....

...Heading 9 Style

By default, eaDocX will use the the Word Heading styles which are built-in to MS word: "Heading 1" etc.

Use these settings to override those settings, to, for example use 'My_Heading_1" instead of "Heading 1".

 

 

Hyperlinking within documents

Most readers of your documents will be familiar with hyperlinked documents. They will be used to the idea that they can follow their own train of thought as they click from one place to another within the www, rather than reading each page from start to finish.

Word has always had the capability of creating hyperlinks within a document, but creating these manually is time consuming, and keeping them up-to-date as the document changes is a huge overhead.

 

Creating Hyperlinks with eaDocX

eaDocX can create hyper-links within the generated part of your document, each time you print a relationship between two elements. For example, when printing the details of a Use Case, you might use Relationship Attributes to print details of the Actors who use the use case.:

Use case

Ref

Details

Used by Actors

Buy Something

UC001

Use case starts when....

Customer, Administrator

Configure something

UC002

Use case starts when....

Administrator

If the Customer and Administrator Actors are also generated elsewhere in the document (in any eaDocX section) then the 'Used by Actors' column can contain a hyperlink to the Actor description. If the Actors are not described, then no hyperlink appears, and the table will look like this:

Use case

Ref

Details

Used by Actors

Buy Something

UC001

Use case starts when....

Customer, Administrator

Configure something

UC002

Use case starts when....

Administrator

To add hyper-links, in the Profile tab, open the Properties window for the element you wish to use as the starting point for the link.  This displays the formatting for the element.

In the "Add information about RELATED elements", select the 'Choose attribute' button:

The Relationship Attributes window will be presented; select the element type to link to, the relationship type and direction.

Finally in the 'Standard attribute' box, choose hyperlink from the drop down menu:

Note, if no relationship exists then a string of text will be added instead.  Default text is "(none)". To change this text go to Tools | Options | Settings.

Designing a document for Hyper-links

Having this facility in eaDocX is more than just cosmetic. It allows you to design your documents in a different way. Because it's so easy for readers to click on a hyper-link to find out more, you need only include a smaller set of information in the main part of your document. Supporting material, such as the Actor definitions in the example above, can but put elsewhere in the document, perhaps as appendices. This gives readers just a core of information to read, but making all the other content easily available.

 

More is not Better

Because eaDocX hyper-links are so easy, and demonstrate the power of the links in your EA model, you may be tempted to put them everywhere. Just as a web page which is packed with hyper-links becomes annoying to read, so a Word document where every other sentence has a hyper-link may also be annoying. It also makes larger documents (those >100 pages) take longer to generate. So, we suggest using the hyper-links feature only where it really adds readability to your documents.

 

eaDocX and Excel "eaXL"

The Corporate Edition of eaDocX gives you many more options for producing excellent documents from your EA Models:

•You can use all the editing features of Excel to manipulate your EA data:

▪Create lists

▪Edit and save values

▪Even add new elements, all using the Excel interface that you are familiar with

▪We do this by embedding Excel directly into your EA interface, which we call "eaXL"

•Once you have got your EA information in Excel, you can then send it off to be reviewed, and allow your reviewers to add new information, which you can then quickly import back into EA. No more messing around with CSV templates in EA : you just press a button to import back into EA!

•When your EA information is in Excel, you can use all your favorite Excel techniques to process the information; creating summaries, looking for trends and really understanding what's happening in your EA project. More...

•All those new Tables and Charts can be put right back into your eaDocX document

•..and eaDocX will update your document, including the Excel tables and Excel charts, every time the document is re-generated.

Related Element Data

EA allows you to capture all kinds of information about your project, but it's real power comes from relating different kinds of information together.

So it's great that EA can store Use Cases and Components, but when you start to relate them together, to say which components are involved in implementing which Use Cases, you are making real progress in understanding your project.

Putting this knowledge about the relationships between 'things' into readable documents has always been a problem. The only solution is often diagrams, which are fine when the number of relationships is small, for example, in a Class diagram.

But as you use EA more, you may find that more and more of your understanding of the project is expressed in relationships: not just classes related to other classes, but classes to use cases, use cases to requirements, requirements to stakeholders.....

eaDocX allows you to make these relationships fully visible to readers of your documents, in a powerful and flexible way.

This is best illustrated using an example.

We've created two types of EA Element: Stakeholders, which are Actors of stereotype <<stakeholder>>, and Requirements. We've also linked them, to show which stakeholder owns which requirements, and even one who is "demanding" requirements (we've attached a note to that relationship, to show there is more information on the relationship).

 

1 - Printing a Single attribute of a related element -  a "Relationship Attribute"

If we now decide to print a quick table summary of which requirements are owned (or demanded) by each stakeholder, we might want to print:

Stakeholder

Requirements

Fred

Requirement 1

Bill

Requirement 1, Requirement 2

Jane

Requirement 3, Requirement 4

To do this, when specifying how to print <stakeholder>Actors, add a Relationship attribute, telling eaDocX to follow 'Dependency' links, and print the name attribute of what's at the other end of the relationship, that is, the Requirement name.

2 - Printing several attributes of a related element - a "Relationship Table"

We might want to print more information about the requirements, for example, to have a table of them after each stakeholder, like this:

1 - Stakeholders

1.1 Fred

Fred is the.....

1.1.1 Requirements

Requirement

Detail

Phase

Requirement 1

The solution shall....

1.0

 

1.2 Bill

Bill is responsible...

1.2.1 Requirements

Requirement

Detail

Phase

Requirement 1

The solution shall....

1.0

Requirement 2

The solution shall....

1.1

1.3 Jane

Jane is the....

1.3.1 Requirements

Requirement

Detail

Phase

Requirement 3

The solution shall....

1.1

Requirement 4

The solution shall....

1.0

In this case, we have a whole table of requirements after each stakeholder. See Relationship tables for more details.

3 - Printing everything about a related element - a "Relationship Element"

Just occasionally, we might want to print a related element in whatever style it is formatted: table or inline. See Relationship Elements.