What to include in your Enterprise Architect documentation

Make the required outcome clear

• Set expections at the start of the document, either in the email subject, or possibly even in the Title…
  • Decision Required: ……..
  • Approval required: ………..
  • I need your help……….
  • This is for information only……….
• Add a call to action at the start of the document.
  • Create a new “Executive Summary” EA package, add your request to the package notes and add the package to your eaDocX document.
  • Or if you have Corporate edition with DM enabled, enter your instructions via the eaDocX “Document Abstract” dialogue (Tools | Document Management | Document Information), and include it as a Section at the start of your document (Insert | Document Properties | Document Abstract)

Organise your content

• Structure your document into Core and Supporting Information with automatically generated supporting information in an Appendix.
  • Create a “related elements” report (Insert Report | Element report and choose Source = Element Cross Reference) to print any or all items referenced in the main body of your document as a separate section – that means the information is there and accessible simply by clicking through a hyperlink but it doesn’t get in the way of your main ‘ideas flow’.

Cut out the unnecessary stuff

Go green and publish a Compact document to eliminate the empty sections – Set this in Tools | Options and Settings | General Settings.​ This reduces paper consumption for readers who need a hard copy, and it makes the document easier to read too.

Highlight the important stuff with colors

Not only can models be made more readable with colors*, documents can too.

You can color-code values that meet particular criteria. Conditional formatting rules which apply automatically when you generate documents from EA, make it easy to see where stakeholders need to focus.

Bring key issues to the attention of your readers by using colors to highlight missing information, or data that is outside an acceptable range. Revisions and edits to your document can be imported back into EA using the Revision Manager.

Or use colored Word table styles as a quick guide to tables for different classes of elements.

*(See this article for more on the subject of colors).

Would a spreadsheet be better?

Some types of information just work better in a spreadsheet. In particular when there are lots of fields (attributes & tagged values) for lots of elements which all need to be viewed together.  Recipients can sort and filter large volumes of information to find what they need quickly.

You can set spreadsheet conditional formatting rules , and if you need to process the ‘raw’ EA data to produce charts and tables using Excel formulae then nothing else will do.

Using spreadsheets is also a great way to collect missing information to be imported back into EA. And if you need to, you can guide your reviewers by defining sets of permitted values.