ea Revision Manager walkthrough

eaRevisionManager lets to take the feedback from your document reviewers, pull together all the comments and changes from everyone, see it all in one place, and push changes directly back into your EA model.

Setup

This walkthough shows you how to take the feedback from many people and process it, so to setup the walkthrugh we need a few things:

• The eaTeamWorks example model, which contains all the data
• Two documents, which are copies of a document generated by eaDocX, and whihc were set to two users.
  • Analysis summary – Charlie comments.docx, sent the ‘Charlie’
  • Analysis summary Jackie and Clare feedback.docx, sent to Jackie, but with some additional comments from Clare.
• Once you have downloaded the model and the two documents, you’re ready to start

Reviewing all the comments

In the eaTeamWorks model, open eaRevisionManager. This is either:

• In the Specialize menu
  or
• Under Specialize / eaDocX, choose Revision Manager

As you open it, you’ll be asked for the documents you want to load. Choose both of the document you downloaded above.

Once Revision Manager has examined the documents, you will see:

• A summary of all the document you loaded, who contributed to them, and about how mange comments and revision there are.
  • In Word terms, a comment is just a note which is attached to some part of the document. A revision is a change to the content of the document. Revision Manager will try to work out exactly what bit of your EA model the change refers to.
    This should something like:
    
    So you can see that Charlie made one comment, and two revisions, and Clae and Jackie made 4 revisions.
• Revision Manager has examined all those comments and revisions, and has tried to tie these bacl to element in your model. This is not a prefect process: someone may have deleted hge bits of the document, and made loads of changes, but Revision Manager will do its best.
  In this case, you should see something like this:
  
• Revision Manager has found two comments on the ‘Use Cases’ diagram.
  • Charlie thinks its too complicated, and so does Jackie. Looks like we’re going to have some work to do here. We can’t do any automated processing on these comments, but Revision Manager has at least told us that two people have comments on the same EA diagram.
  • Looking now at the ‘Manager’ Actor. Both Charlie and Jackie have commented on this, and it looks like we need to use what Charlie wrote. As she’s written quite a lot, use the ‘more details’ to see the whole change.
    That looks fine, so we will accepts that change – click on the ‘tick’ icon
  • This adds the change to the Pending Changes list, so no change has been made to EA yet. We think it’s best to see all the changes to the whole document before we make any changes in EA. That way, if a change in one place affects a change somewhere else, we can think about that.
  • The next change is the to ‘Supplier’ Use Case description, and as only Jackie has provided any feedback, lets accept that, and it gets added to the Pending Changes
  • Notice how, when you accepts a change, Revision Manager moves you on to the next change straight way
  • This next one looks harder: Charlie has provided some useful information, but Jackie and Clare seems to want to take a different approach.This is exactly what Revision Manager is for: helping you to sort the simple changes from the hard ones, and this one is ‘hard’. WE suggest not accepting any of the changes: this will need some more serious action, offline from EA
  • The finally changes, all suggested by Charlie, are more definitions for these attributes from the domain model. just accept all of them: Charlie knows what they are doing.

Making the changes to EA

The last part is the simplest. Just click ‘Save to model’.

There is also an option to ‘Save with details‘. This will add a new element, as a child of each of the elements you are changing, which captures details of the change: who made it (from the Word document – so in this example, Charlie, Jackie or Clare), the old state of the data and the new. This might be useful if you want to keep a really code track of who made what changes.