Why you need excellent documents and how to produce them… with Enterprise Architect and eaDocX

2012

Why you need
Excellent Documents
And how to produce them… with Enterprise
Architect and eaDocX
This document looks at ways to structure and create project documents that
help readers to find and use information that is relevant to them. For both
Waterfall and Agile developments, documents can improve project quality and
give new insights. New document capabilities allow authors to create high
quality, accurate and targeted documents, and allow readers to navigate their
way through them in an intuitive way. By storing information in EA, and using
eaDocX, approaches are described that can bring our project communications
into the 21st Century.

Ian Mitchell & Jackie Mitchell
eaDocX Ltd
6/12/2012

Why You Need Excellent Documents
Contents

Abstract ................................................................................................................................................... 3
1 Introduction .................................................................................................................................... 3
1.1 Why Do We Need Documents? .............................................................................................. 4
1.2 Documents - a bit old-fashioned? ........................................................................................... 4
1.3 Reinventing Documents .......................................................................................................... 4
1.4 Tools ........................................................................................................................................ 5
2 Making the Content Relevant ......................................................................................................... 5
3 Documents and Project Development Approaches........................................................................ 6
3.1 Waterfall, Agile, or something else? ....................................................................................... 6
3.2 The 'V' Model .......................................................................................................................... 7
4 The Customers for your documents ............................................................................................... 8
4.1 Upstream Customers .............................................................................................................. 9
4.1.1 Multiple Views .............................................................................................................. 11
4.1.2 Helping the reader ........................................................................................................ 11
4.2 Downstream Customers ....................................................................................................... 12
4.2.1 Packaging ...................................................................................................................... 13
4.2.2 Multiple Views .............................................................................................................. 13
4.2.3 Informal and formal documents ................................................................................... 13
4.3 Testers ................................................................................................................................... 13
4.4 Project and Programme Managers ....................................................................................... 14
4.4.1 Progress reports ............................................................................................................ 14
4.4.2 Scenario planning .......................................................................................................... 15
4.4.3 Risk and Issue management.......................................................................................... 15
4.4.4 Contract and Subcontract Management ...................................................................... 15
4.4.5 Stakeholder Management ............................................................................................ 15
4.4.6 Ad-hoc meetings ........................................................................................................... 16
4.5 Peers...................................................................................................................................... 16

2 ©eaDocX Ltd 2012

5 Conclusions ................................................................................................................................... 17
Appendix A. About Enterprise Architect (Sparx Systems) ................................................................. 18
Appendix B. About eaDocX ............................................................................................................... 19
Appendix C. About the Authors ........................................................................................................ 20

Abstract
This document looks at ways to structure and create project documents that help readers to find
and use information that is relevant to them. For both Waterfall and Agile developments,
documents can improve project quality and give new insights. New document capabilities allow
authors to create high quality, accurate and targeted documents, and allow readers to navigate their
way through them in an intuitive way. By storing information in EA, and using eaDocX, approaches
are described that can bring our project communications into the 21st Century.

3 ©eaDocX Ltd 2012

1 Introduction

1.1 Why Do We Need Documents?

Despite the democratisation of data, and the instant access to information which is now possible via
networking tools and media, the creation of documents remains a common requirement for people
who work in or with large organisations:

 to pitch proposals
 to communicate progress
 to define project status at a point in time
 to allow sign off of a milestone or a work package
 to agree contract deliverables
 to indicate project compliance
 to coordinate between multiple teams
 …
Some of these are one-off documents. Others, once created, need to be maintained, updated,
amended, reviewed, augmented, included in others… And when there are lots of stakeholders
involved the overhead of managing these documents becomes significant. Most companies don’t
have the luxury of dedicated document authors but rely on the analysts, designers and testers to
create their own reports and specifications. In doing so, the ‘doing’ of a project has to stop to allow
for this ‘reporting on the doing’.

1.2 Documents - a bit old-fashioned?

You may work in an organisation which can deal with informal specifications and reports. But the
organisations we deal with still live and die by the formal document, as a statement of where we are
and what we want. So making those documents relevant and accurate, and creating them
efficiently, is a problem worth solving. But we don't want to stop 'the doing' for too long.
As new technologies have become more available to business users, the expectations that they bring
to documents have changed. For people used to browsing well-designed, well-linked websites, the
linear document they are given at work can be a bit dull. Readers don't expect to start reading a
document at page 1, and carry on to page 100. They expect to browse a document as they would a
web page: read a bit, follow a link, read a bit more, go back, carry on…

1.3 Reinventing Documents

This article will explore how we can create documents which fit these new expectations, which mean
they:
- contain content which is relevant to the reader
- engage and hold the reader's attention
- guide the reader as to where they should concentrate their attention

4 ©eaDocX Ltd 2012

- give the reader freedom to navigate the document’s contents as they wish

1.4 Tools

The tools we use to capture, model and analyse systems are critically important in defining how easy
it is to create these intelligent documents. This article examines two tools in particular: Enterprise
Architect (EA) - one of the most popular modelling and design tools, and eaDocX - a new document
generation add-in for EA. The ideas in this paper could be applied to other modelling tools and their
document generators, but our experience is with these two, and we think they are good enough for
the needs of most organisations. And good enough is, well, good enough.
EA is flexible enough to allow you to capture almost anything about your project: requirements and
business needs, architectures and components, user stories and hardware topologies. This article is
not going to describe how to do that initial capture; we're concerned with getting that captured
knowledge into the heads of the people who need it, with intelligent documents.

2 Making the Content Relevant

As business or IT professionals, we know that creating documents is hard work. Our documents
need to contain lots of information, and may take us days or weeks to create. It's not surprising
therefore that whenever possible we produce a single deliverable document, even though it will be
read by a variety of people. After all, creating one document was hard - creating several, so that
they are all consistent, is unimaginable.
But when the content for the documents comes from a model, making documents consistent is easy.
All we have to do is not change the model in between generating the documents. This means we
can move away from the one-document-for-everyone approach. When documents come from
models, we can produce radically different documents for each of our 'customers', tailored to their
needs. This way, they only get the information relevant to them, and so there is a greater chance
they might actually read it.
However this introduces a new challenge. When our documents just contained everything we knew,
there was little choice of content - put in everything! With model-generated documents, we can,
and should, choose what we put into each document.
We have found that there are three main things to think about for any document. If we get them
right, then we're on the way to producing excellent documents:

 Appropriate detail. Give your customers information which they can understand and use,
not all the information you know.
 Traceability. Show the story of where ideas came from, and where they are going, as well as
what the ideas are right now. EA is great at capturing this, and eaDocX can be used to show
it. This helps users to understand something of the bigger picture.
 Multiple views. Don't assume that just because you can understand a UML Domain model
that your readers can too. So present the same information in several ways. This gives
readers a bigger chance of understanding what you are showing them. Some readers will

5 ©eaDocX Ltd 2012

love diagrams, others prefer lists. So give them both. The EA model will make sure the two
contain the same information.

3 Documents and Project Development Approaches

3.1 Waterfall, Agile, or something else?

Our experience, from working in both Waterfall and Agile development environments, is that most
projects don’t fit either EXACTLY.
 There is usually a mix of infrastructure and technology – some requiring Waterfall
development, and some Agile.
 Within waterfall development there can be phases of releases.
 The delivery timescales mean that some work has to start early (at risk) using assumptions
rather than having a full set of signed off inputs.
 Factors outside the control of the project will change development priorities and
deliverables.
So the development ‘methodology’ in a particular project is usually a hybrid of types of
development, including formal planned Waterfall and Agile activities, phased releases and some ad-
hoc changes. We have assumed this hybrid approach for all that follows.
Most projects will contain overlapping phases, developments and changes. So at any given stage of
the project, you will have

 almost complete information from the last phase or work package,
 an increasing amount of stuff from your current phase of work,
 some limited knowledge of the next phase,
 and within any given phase, areas of analysis that are almost complete and others that are
not yet started

'Pure' waterfall. Documents can't contain Overlapping waterfall - we may know something
information from multiple phases about several phases.

6 ©eaDocX Ltd 2012

Overlay this picture with options (in the form of Change Proposals or Change Requests, Risk
scenarios or mitigations) and we have both a challenge and an opportunity. A document from any
stage could contain information about the previous stage and the next one, as well as the current
one. Some of the information is approved, some is proposed, and the level of available detail varies
across the project.
Traditional documents usually focus on answering one particular question, for one specific phase,
and are produced by one team with one perspective. This is sensible because unless the team is a
small, cross-functional one, the teams delivering the different stages are from different parts of the
business, and may be even using different tools, techniques and knowledge stores. But to really be
valuable, we would like our documents to capture all these types and levels of information and then
guide our readers through the complexity.
This is the model, and the challenge, that we are addressing; a real-world, complicated, overlapping
model with multiple teams and many documents.

3.2 The 'V' Model

There are as many ways to illustrate the flow of information through software projects as there are
software projects. We like the 'V' model illustration, as it has the idea of starting with a business
problem, and finishing with a business solution, going via a deep dive into implementation details
and then collating those details into solutions.

Most of the examples in this article are from the point of view of a Business Analyst, close to the top
on the left hand side of the ‘V’, but they apply equally well to any point in the left-hand side:
Requirements capture, Business analysis or architecture & design. And once implemented here,
they can flow through to the rest of the ‘V’ model.

7 ©eaDocX Ltd 2012

4 The Customers for your documents

Wherever in the left-hand-side of the 'V' model we are working, we will have multiple customers for
our documents:

 Upstream customers. Whatever we are doing, there will always be some information passed
to us by the previous part of the process. At the top of the V, this may be a business
strategy, business goal or a set of very high level requirements. As projects progress through
the levels, the amount of information generated upstream increases. And we need to
communicate back up the stream.
So the people who have passed information to us are our first set of customers.

 Downstream customers. When we've finished playing our part in the software process, we'll
hand over what we have done to someone else. For a BA, that means handing over to
architects or designers. For a designer, then the handover will be to detailed design or
implementation.
The kinds of information these people need will be quite different from that needed by the
upstream customers so we consider them our second set of customers.

 Tester customers. The most neglected set of customers: the testers. They take what has
been specified on the left hand side of the V, and use that to test what they are given from
the layer of testing below them. For example, Acceptance testers take the results and
deliverables from System Testing and apply business analysis ideas to validate the solution.
If as a BA or designer you've ever managed to get some early input from testers at the start
of a project, you'll know what a valuable insight they can bring. And if you ARE a tester, you
may be getting tired of being an afterthought...
This is our third set of customers.

 Project and Programme Managers. These have another set of reporting requirements,
usually to do with progress, completeness, identification of risks and issues, impacts of
potential changes, how much it is all costing and when will it be finished.

8 ©eaDocX Ltd 2012

Producing documents for this stakeholder group, or providing information to help produce
management documents, creates the fourth set of customer requirements.

 Peers. The final customer group, our most demanding audience, are those who review our
work for completeness, accuracy and compliance with standards. This review forms a key
part of quality control. Our peers may not know the content as well as we do, but they will
know the style and quality of what we should deliver, and be able to judge its completeness.
Let's now look at how we can help each of these customers in more detail.

4.1 Upstream Customers

Documents for upstream customers have a particular challenge, so for a moment, put yourself into
their position.
Maybe they were asked to go to some workshops, to provide their knowledge to the project, but
now they have moved on to do other things. They no longer have lots of time for more workshops
or design sessions. And now, after they have been back in their normal job for a while, a document
arrives in their in-box, asking them to 'sign-off' what's inside it.
If they are going to read what you send them, and add value to it, it had better be easy to read, clear
and concise. Don't bother sending them the full analysis detail - they won't read it. They need to
know that what you have done will satisfy the objectives of their customers
What you're going to need is therefore:
1. A good introduction to the project, bringing-in the context and top-level ideas for the
project. This will help them remember what this was all about. This means the ideas which
are one level above them in the 'V' model - two levels above you. So if you are a BA, and the
upstream customer is a domain expert, it would be good to see the board-level or strategic
requirements which caused the project to be created in the first place.

2. The information which they gave to you, in a way which they can understand. This means
no technical details, just simple requirements, user stories or use cases, maybe with some
screen- or process designs if they are available. In each case, an upwards trace back to the
top-level (board) requirements would be helpful, so they can check that what they asked for
is consistent with what their managers wanted.

For example:

9 ©eaDocX Ltd 2012

Ref Requirement Implements strategic requirements

REQ001 The solution shall... (BR-001) Improve customer satisfaction

RES234 The solution shall.... (BR-002) Improve customer retention,
(BR-003) Improve margin

Example of upwards-traceability. The hyperlink can lead to an appendix where the relevant
strategic requirements are presented in detail.

Be realistic about what any document can deliver. You can remind them that, for example,
Requirement REQ001 traces back to board-level requirement BR-001, but only they, the business
expert, can read the two requirements to see if that's really true. But you have at least asked them a
specific question which they should be able to answer.

3. Finally, you'd probably need to include what's happening next - have their requirements
been ignored, forgotten or lost, or are they being used to inform the next stage of the
project? Here, the traceability isn't something they are being asked to sign-off, so it's a good
idea to say so in the document. But they can still have a role in seeing how, for example,
their use cases are being delivered by the architects/designers. We call this downwards
traceability, and it will mostly be incomplete, as the next phase is lagging behind this one.
For example:

Ref Use Case Implemented in Components

UC123 Create new widget

UC345 Configure gadgets Widgets & Gadgets,
Configurator

Example of downwards-traceability. The hyperlink shows if there are any components which
implement the use case. A missing link may mean the designers haven't done that yet, which is OK
in a draft document - but it may be a serious mistake if it's in the final version.

If the upwards-customer wants to, they can even follow the link and have a look at how it will get
delivered. They may not know enough to judge whether the technical solution is correct, but they
may be able to spot where an error has been made, where what they meant to ask for won't get
delivered. This should both reassure them that something will happen to their requirements, and
give you a chance to add value to the downstream project activities.

10 ©eaDocX Ltd 2012

Hyperlinks that provide this level of traceability are great at improving the readability of documents,
but are time-consuming to create and difficult to maintain manually. eaDocX helps by looking in the
EA model for related elements and automatically creating the links when they are present.

4.1.1 Multiple Views
The above should be seen as the basic information the upstream customers need. But if we are
taking the information for the document from a model, we can give them much more.
Where possible, we're big fans of User Interfaces as ways of showing users what they may be
getting. The most common objection to including this is that it's a piece of detailed design which
belongs much further down the 'V'. [Note: We're using the 'Hand drawn' style of EA diagrams for
these.]
So why not include a diagram like this?

EA 'Hand-Drawn' diagram style

Readers seem to grasp immediately, just by the style of the diagram, that these are just illustrations.
But it's worth saying so anyway. And they can also be traced-back to requirements and uses cases,
and so provide another way for users to approach the document.

This is just one example of this idea of multiple views. Your project may have different information
which it could include, but think about doing it anyway: you may get more questions from readers,
but it's another way for your documents to engage them in your project.

4.1.2 Helping the reader
There will be some parts of your document to which you'd like the reader to pay particular
attention. This may be due to missing data or links, numbers which are outside the expected ranges,
or just issues which are urgent.


EA will let you capture the data for this, by, for example, giving issues a High priority, or a particular
stereotype. eaDocX will then let you highlight these using its Conditional Formatting feature. This
can show, for example, where a link is missing, by highlighting it in a particular colour. Or you could
print a particular stereotype in a different style:

Ref Use Case Implemented in Components

UC123 Create new widget No Component - Is this a
problem?

UC345 Configure gadgets Widgets & Gadgets,
Configurator

Example of eaDocX Conditional Formatting. eaDocX has been told “when there is an empty cell in
this table, print some additional text and colour-highlight It”. This makes it much more likely that a
reader will notice the gap, and do something about it.

4.2 Downstream Customers

We're going to ask you again to put yourself into the mind of another part of the development team
- those who are downstream from you. For example, if you’re a BA, put yourself in the mind of the
Architect or designer. What do they need to get from the BAs who come before them in the
development process?
It certainly isn't the same document you produced for your upstream customers: that was a
business-focussed document, with lots of detail about the whys and hows of the business.
In a hybrid project development, this document is likely to be one of a number which provide “the
best set of information we have at the moment” to the downstream team. They will have already
started the process of tracing from your ideas - Requirements and use cases/stories - to more
architectural and design ideas. It seems reasonable to include this in the document which you give
to them.
Remember that they may not be asked to sign-off this document. It's enough that they understand
what's being asked for, and so linking your ideas to theirs may help with that. So if the 'Business
Analysis' document starts to say which technical components implement which use case, that's only
because that’s what they told you, so it makes sense to include it in a document aimed at them.
In this context, the document we create for this stakeholder group can just include the technical
implementation ideas linked to the appropriate use case/requirement, but maybe with more or
different information – tagged values or attributes of the different classes of information to those
needed by the ‘upstream customers’. Again, make sure it's clear that this isn't what the document is


principally for - they may not yet need to sign-off that requirement X is delivered by component Y;
it's just a helpful way of sharing ideas.

4.2.1 Packaging
It may be more helpful to organise the upstream requirements according to which component
implements them, instead of by business area or stakeholder. You can do this using EA & eaDocX, by
printing by Component, with all the related requirements/use cases, rather than just the packages of
use cases.

4.2.2 Multiple Views
Downstream customers should also be given visibility of the issues which are outstanding from the
previous phase and what aspects of the analysis are affected by those issues. This may well affect
how they approach the design. Use EA Model Searches and eaDocX Element Reports to print this
information.
The same conditional formatting and highlighting which we applied to the upstream document can
also be used here. Especially as downstream documents tend to have more to say than upstream
ones, so helping readers to concentrate on the important bits is even more important.

4.2.3 Informal and formal documents
Although what has been described here is a good way of producing working documents, this
approach can also be used to inform and improve the formal deliverables that do need to be signed
off. In these cases data requirements can be agreed between the various teams in the project
development process and then used to create new standard document structures.

4.3 Testers

This is the group which has historically been an afterthought. At the time when the BA is producing
the requirements document, the testers may not yet have joined the project. By the time they
arrive, the analysis documents are done and signed-off, and the analysts have gone.
But with the approach we're suggesting, even if the BAs have moved off to the next project, we can
still produce documents which are specifically tailored to the needs of the testing community.
What testers need is:

 As much detail as possible about the requirements/use cases/user stories. This will form the
basis of their test cases, and if any were de-scoped after the business analysis was
completed.
 A mapping of where each of those has been implemented in the solution, so they know
where they should expect to test each one. In fact, this is probably the best way to present
the requirements: not by business area, but by the system which implements it.
 An understanding of the current issues, from analysis, architecture, design and
implementation, as well as those being carried-forward from previous testing phases.


 In case there are problems in testing, an understanding of the ownership of each
requirement or use case is very useful, so they can go back to the owner or domain expert to
check their results.
As you can see, this is information which has been gathered previously in the project but can now be
presented in a way which is appropriate for this group of customers, focused exactly on their needs.
Documents can be created containing reports that present the model information starting from use
cases, or requirements, or systems, or owners. In each case the reports can print whatever
information is required, and include links to any related attributes of all related element. The data in
these reports can be filtered and sorted to allow testers to focus on specific test cases and scenarios.
Once the source information is available in this way, test cases and scenarios can be included in the
EA model and linked to the relevant existing elements. Then the test reports can also include
hyperlinks to requirements etc. and be created or organised by owner or by system, in the same way
as previously described. In this way it is much easier for business owners to understand the
significance to the project (with requirements or use cases impacted) when tests fail.

4.4 Project and Programme Managers

In addition to specific project technical deliverables, this set of stakeholders have specific needs that
are associated with daily, weekly and monthly reporting cycles. The amount of work needed to
support this set of requirements can be dramatically reduced by holding information in a shared
repository and using standard, automatically generated documents and reports.

4.4.1 Progress reports
Regular reporting of status against project deliverables is a typical requirement. Just

 extracting the information from the analysts and designers,
 manipulating it to suit the reporting template and then
 adding data held elsewhere
can take most of a Project Manager’s time and create a significant overhead for the project team
who need to provide the information. The use of EA as a single repository for the project, for
example linking risks and issues to the requirements, stakeholders, use cases and business benefits
and phases of delivery, can provide huge benefits for the creation of reports.
Just as with any other document, choosing subsets of data for each report produces a highly
targeted and useful tool for readers.
With EA and eaDocX we can take a view of just a specific package or create a report that looks across
the project as a whole. It is possible to filter and sort on items of interest and then apply conditional
formatting to highlight areas of interest, omission or inconsistency. Once each document has been
set up it can then be regenerated whenever it is needed to provide an updated view of the project.
In this way the documents allow good quality decisions to be made with the correct information –
and the detailed formatting means that Project Managers can avoid local manipulation of data (and
therefore risk of error) that is often a characteristic of complex projects.


4.4.2 Scenario planning
Change management, and in particular change impact analysis, can be greatly improved by the
inclusion of an integrated set of data. Rather than creating a new set of analyses outside the project
and setting up an alternative model, it is possible to flag the set of elements that will be impacted by
a proposed change - either by implementing a tagged value for change number or by creating a
change element and linking it to all the impacted parts of a project. This can then be used to
produce focused reports to assist in the impact assessment of changes – by area, by stakeholder,
whatever you need.

4.4.3 Risk and Issue management
This approach is also useful for risk assessment and issue management. We can produce

 tables of risks and issues using conditional formatting to highlight high, medium and low
probabilities and impacts,
 lists of requirements or use cases or stakeholders impacted,
 details of the impacted areas in a separate Section or Appendix, using the Element Cross
Reference Report.
This allows for a richer understanding of the risks and issues and better informed management
decisions. For more information on this topic, see the White Paper: Risk and Issue Management
using EA and eaDocX on the eaDocX website.

4.4.4 Contract and Subcontract Management
Most projects don’t deliver using entirely ‘home grown’ talent. Bespoke products and skills are
often bought in for specialist activities – either as part of the delivery or as part of the final solution -
and there is usually contract paperwork to be signed along with agreements of scope and
deliverables. EA can be used to capture and define the requirements and interfaces that make up
the contract deliverables and scope. Then documents can be generated to provide clear statements
of work and areas of responsibility.
So a supplier can be given a document which contains just the subset of the project information
which they need to know, but drawn from the 'Master' model, so it can be easily updated when
needed.

4.4.5 Stakeholder Management
This is what all documents are ultimately about – keeping stakeholders happy. And what better way
than to create a document for each individual stakeholder with all the requirements, use cases,
interfaces, risks etc. in which they are especially interested. eaDocX allows us to simply print
everything that is linked to a stakeholder. As long as the link exists in the EA model then the
document will print it.


If you're looking for a quick and simple justification for adopting these techniques, then this has
proved to be a good one: just produce documents for named individual stakeholders, with just their
own issues, requirements or ideas, and see how they suddenly see the value of what you're
proposing.
It is also possible to use these links to capture other data in the EA model, for example to produce
RACI matrices for requirements, use cases, test data etc to assist with management of project
approvals. Take a look at the eaDocX website for a detailed guide to creating a RACI report.

4.4.6 Ad-hoc meetings
Sometimes exceptional meetings are called by the Project Manager to address particularly difficult
or urgent issues. At times like this it is necessary to have a range of types of information, usually
extracts from a number of parts of the project that need to be gathered from several teams, system
and process designs and analyses.
If the project data is held in EA, then the items for discussion just need to be gathered together in a
single EA diagram, and then the contents of the diagram can be printed straightaway with whichever
details are needed. In this way an urgent meeting can happen and be productive as soon as it is
needed – rather than having to wait until the information can be pulled together.

4.5 Peers

This customer group can be overlooked, as it is easy to expect them to have access to the model and
be able to find the information they need. However, for someone outside the project, it can
sometimes be difficult to find your way around someone else’s model. Peer review is usually
required for quality control, and all the required information must still be presented in a clear way
for this to be done efficiently.


Certain aspects may be subject to more scrutiny than others due to application of modelling
standards or technical directives. Therefore the documents need to be able to focus on those
attributes or classes of element to ensure completeness and compliance. One application of this is
to use eaDocX to print relationships based on link type – if multiple link types have been used then
the document will highlight the inconsistencies and indicate where the model needs to be
rationalised.

5 Conclusions

In this paper we've tried to give you some ideas about how to produce excellent documents that will
transform your project communications. When most, or all, of your project contents are in an EA
model, then your project has a 'single version of the truth'.
Now, not only can you present your project information, analysis and design to different people in
different ways, but you also have more chance of spotting errors and inconsistencies. These may be
errors which have crept in during a particular phase, or more likely, have occurred when passing
information between phases or teams. With multiple tools such errors can go un-noticed until it is
too late. We don’t guarantee you won’t have errors if you use a single modelling tool (although
we’d like too!); it is just much easier to spot them early. All kinds of benefits can flow from this,
with more accurate and relevant documents that allow valuable people to concentrate on what's
important.
Excellent documents give new insight, are focussed on specific outcomes and meet the needs of our
project and business customers. They are interesting and engaging to read, and act as a quality
improvement tool rather than an administrative overhead. Using EA and eaDocX, document
generation is simple and fast. The resulting documents are business-ready and will transform your
projects.
That’s why we need excellent documents.


Appendix A. About Enterprise Architect (Sparx
Systems)

Enterprise Architect is a visual platform for designing and constructing software systems, for
business process modelling, and for more generalized modelling purposes.
Enterprise Architect is based on the latest UML 2.3 specification (see www.omg.org). UML defines a
visual language that is used to model a particular domain or system (either proposed or existing).
Enterprise Architect is a progressive tool that covers all aspects of the development cycle, providing
full traceability from the initial design phase through to deployment, maintenance, testing and
change control.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Sparx Systems is an Australia-based company with a solid history of innovation and development
within the modelling tools market. Sparx Systems is a Contributing Member of the Object
Management Group (OMG), the standards body responsible for defining and maintaining the UML
and related specifications.
Sparx Systems believes that a complete modelling and design tool should be used throughout the
full software life-cycle. Our subscription plan reflects this, as does our belief that ‘life-cycle’ software
should be as dynamic and modern as the systems you design and maintain.
Sparx software is intended for use by analysts, designers, architects, developers, testers, project
managers and maintenance staff; that is, almost everyone involved in a software development
project and in business analysis. It is Sparx Systems' belief that highly priced CASE tools severely limit
their usefulness to a team, and ultimately to an organization, by narrowing the effective user base
and restricting easy access to the model and the development tool. To this end, Sparx Systems is
committed to maintaining an accessible pricing model and to distributing a free 'Read Only'
(Enterprise Architect Lite) version of Enterprise Architect for use by those who only need to view
model information.
Contact Sparx Systems at the following email addresses:
• Sales and Purchase Enquiries: sales@sparxsystems.com
• Product Support Enquiries: support@sparxsystems.com


Appendix B. About eaDocX

Business-ready MS Word reporting from Enterprise Architect

eaDocX is the high-quality Microsoft Word document generator for Enterprise Architect (Sparx
Systems).
It combines an intuitive user interface with tight integration with Word, producing ready-to-publish
documents with a couple of clicks. You'll save hours: creating documents using the built-in
formatting, then customising them to make your documents look exactly the way you want.
Whenever your EA model changes, a couple more clicks will pull in the latest from your EA model,
directly into your Word document.
 Simple to create great-looking documents
 Use formatting from your favourite Word documents
 Automatically create hyperlinks within your documents
 Access to all Enterprise Architect content
 One-click re-generation

This represents a significant breakthrough for Enterprise Architect users. Now a whole project team
can use EA as their knowledge repository: analysts, architects, designers, developers and project
managers, because each can define their own documents, customised to their exact requirements.
eaDocX started out as a solution to a very specific problem. How to produce 1000+ pages of
complicated technical design documentation - Use Cases, Domain models, sequence & state
diagrams and architecture descriptions - written by 6 people, for a very smart but critical audience.
And produce it in 6 different but overlapping documents, with a new version of each document
every other week.
Enterprise Architect was the obvious choice for the tool in which the design would be produced, but
how to produce the documents?
The only solution was to generate the documents directly from EA.
Six years, and many projects later, and after a port from VBA to VB.NET and new user front end, the
result is eaDocX.
As we are experienced EA users - for both Business Analysis and Architecture/Design - we know what
it takes for a generator to be really useful. Fast, simple and comprehensive. So that's what we've
built. We hope you enjoy using it.
Website: www.eadocx.com
Email: enquiries@eadocx.com


Appendix C. About the Authors

Ian has been a Business Analyst for more than 15 years, working mostly on
telecoms and finance projects. He also teaches and mentors project teams in
how to use UML and the Enterprise Architect (EA) tool. He has a particular
interest in the 'multi-model' approach to business analysis, using a wide variety
of models to understand the business.
Ian is also the designer of the eaDocX document generator for EA, which he developed to make his
time working with clients more effective. He now focuses on helping BAs spend less time typing,
and more time thinking.

Jackie Mitchell has worked in the Aerospace, Health and IT industries for more
than 25 years, as a project and programme manager, consultant and trainer. She
has worked on multi-national technology projects of all shapes & sizes, most
recently in Telecoms, using Waterfall and Agile methods. She has a particular
interest in making sure that teams are using the right tool for each job and in
optimising the use of information – to help the technical team do the right things right and minimise
the administrative and management burden - delivering quality, on time and to cost, and keeping all
project stakeholders happy.


Why you need excellent documents and how to produce them… with Enterprise Architect and eaDocX

More Related Content

What's hot (17)

Viewers also liked (20)

Similar to Why you need excellent documents and how to produce them… with Enterprise Architect and eaDocX (20)

Recently uploaded (20)

Why you need excellent documents and how to produce them… with Enterprise Architect and eaDocX