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.