This is the second article in the series which describes simple techniques to improve the effectiveness of EA model sharing.
In the first article I discussed hints for cleaning the content that already exists in your model so it makes sense to a new user. The next step is to help them find their way through it – do they just start with the first package and work down the project browser item by item, or is there a better way?
NAVIGATING YOUR CONTENT
1. ‘Readme’ diagrams
Readme diagrams are a great way to tell new users a story: where to look first, then what next, and develop your ideas step by step.
Most models contain just the diagrams needed to deliver the project:
But new users need more clues. So think about what new stuff you’ll need to create to help them.
Why not create a family of diagrams which are just intended for new users? I call them ‘readme’ diagrams. Users should quickly recognise that this is the diagram to look for when exploring a new bit of the model.
I recommend giving these diagrams their own stereotype (yes, EA diagrams can have stereotypes) so that all these diagrams can be excluded from existing documentation and don’t get in the way. (For eaDocX users, see diagram filters)
I tend to put all this new stuff into new packages, all called ‘Viewpoints’, and also give them their own package stereotype, so they can be excluded from documents as well:
Within diagrams, use EA diagram hyperlinks to show users which existing diagrams to look at, or which new ones (see below), and include lots of helpful notes:
2. New diagrams
The Readme diagram (above) contains hyperlinks to some new additional diagrams, which can be created just for new users.
These diagrams are more specific than the general ‘readme’ diagram. They show just one aspect of the model, and are designed to help users on their journey towards understanding the model.
For example, I created some diagrams which help users to understand two key parts of our overall domain model: Journeys and Payments:
Note that we’re using all the modeller’s tricks here: we have used colouring to show what content is part of each model idea, and laid-out the diagrams to show the hierarchy of those ideas. It would be hard to put these onto the overall project diagram (above) – it would make reading the diagram just too complicated.
Note that these diagrams also only have a small number of ideas in them: in this example, just domain model classes. They might also, for example, show how Components relate to Use cases, or Requirements to their stakeholders. In all cases, keep these diagrams simple, and easy to understand. Even if they don’t tell the whole story.
3. EA Model Views
The idea of ‘model views’ has been in EA for a long time, but seems not to be used much, which is a shame, because it’s great for helping people understand models.
EA Model Views can have a ‘favourites’ kind of folder, into which you can put diagrams, elements and packages, and control their sequence. This nicely fits into the idea of a curated set of EA content, which can help to explain a model.
So you can create a set of these ‘Favourite’ Model Views, for the different kinds of new users:
Using diagrams and Model Views in this way delivers a friendly introduction as new users start to explore your model. Combined with the simple cleaning tasks described in the first article in this series, the job is almost done.
Next… #3: Validating