Getting the project structure right in EA is an important step to understanding how EA works and makes the process of generating documentation a lot easier.
Lets take a look at the standard project structure when we create a new EA project
Select 'File' -> 'New Project' and enter a file name and location for your project
Then select the type of model you wish to create for the purposes of this demo I've gone with 'Requirements' and 'Use Case'
You should now have a blank project from which to build your model.
On your right (if you haven't moved things around) you should be able see the (empty) project browser window.
You are presented with a blank model, with the first (root) element of the project named 'Model'. If it helps, you can rename this element to something more appropriate, such as the name of the project, or stream of work.
At this point, think of the project browser as a form of folder structure where the 'Model' element is the C: drive and you will begin to create 'packages' under it to organise your work.
Tip: If you can't see the project browser, hit 'Alt + 0' or 'View' -> Project 'Browser' from the file menu.
So now we want to build out some structure to the form the skeleton of our model. This will help guide users both viewing and adding to the model, and help when we move on to working with the document templates later on.
If you recall we selected this project to be a 'requirements and a use case model,' so we now want to create a container package for each of these. So go ahead and make two packages, 'Requirements Model' and 'Use Case Model' under the 'Model' element.
To do this, make sure the 'Model' element is selected and click the small 'folder' icon on the project browser toolbar.
This will pop up a window to create a new view and ask to select a type. This really only affects the type of icons used for the package, but go ahead and select 'Use Case'.
When you have added both packages, you should see something like the below image.
Note: The two package icons are different as I selected the 'simple' view icon for the requirements model package
There is another option here to create a package from a wizard - this may help your understanding of how to structure your models as it creates a number of elements by default.
To create a model from a wizard, right click the root element 'Model', and select the appropriately named 'Add a New Model using Wizard' option.
We are presented with the same window as earlier when we created a new project.
If you select 'Use Case' here and hit 'OK', it will go ahead and create another package named 'Use Case Model', this time with some pre-created elements thrown in to boot. Let's go ahead and look at what its created.
Here you can see the elements generated by the wizard - a sample use case diagram, a package each for actors and use cases and same sample elements.
The generated use case diagram gives some explanatory text on what each element does and how it relates to other UML elements.
We can either start with this model and edit the generated elements or just start from scratch. For clarity, lets start from scratch by deleting the generated diagram and retaining the generated elements (Packages, Actors and Use Cases)
Right click the 'Use Case Model' diagram and select 'Delete Use Case Model'
Now ensuring we have the 'Use Case Model' package currently selected, select the 'New Diagram' button within the project browser
EA will then bring up the new diagram dialog where you can select a type of diagram to create and prompt for a diagram name.
In the example below I have named it 'Search for books'
So what does this have to do with project structure? Documentation in EA centres around having a well organised model therefore allowing the flexibility to generate documentation at the required level – either at the micro or macro level.
By containing our various elements within packages, appropriately structured and named, we can quickly generate highly specified, focused documentation or higher-level, broader documentation without the hassle of manually adding or removing content after generation.
Let’s build up our sample model a little more to represent what you would actually use.
Here I have added 5 ‘root’ packages that contain distinctly different models:
- Requirements – to hold the all important requirements model
- Use Cases – to hold the use case/user story expansions to met the requirements laid out in the requirements package
- Domain Model – a conceptual data modelling area to map out the data model. Can and should be supplemented with a a logical (physical data model as system is developed)
- State Transition Model – a later-stage model but important when rest of the model matures and complexities arise. Particularly useful when reverse engineering a system
The reasons for why this is important may not be immediately clear but should make more sense when it comes time to generate documentation from our model. More on that in my next article! In the mean time, happy building!