Enterprise Architect; the Custom Document

Custom Documents; A good alternative to the Documentation Generator

Introduction

A recent addition to the functionality of Sparx Systems Enterprise Architect (EA) is Custom Documents. This feature is provided in addition to the existing feature of documentation generation.

This article provides details of this new feature, compares it to documentation generation and poses the question:

“Are custom documents a replacement for Document Generation?”

What is a Custom Document?

A Custom Document is a new featured in EA represented as an Artefact element with the stereotype <<CustomDocument>>.

This element, like all elements in EA, has a single Linked Document which can contain:

Static content – this is exactly the same as an other Linked Document in EA
Dynamic content – linked to a Package, Element, Diagram or Feature in the Browser and formatted according to a Document Generator Template

The linked document then displays the resultant document with static content displayed “as-is” and dynamic content displayed using the information within the associated Template.

The custom document can be exported to various formats:

DOCX
PDF
RTF
HTML

Overview of the Document Generator

The Document Generator has been a feature of EA for a very long time and is based upon a system of Templates. A template determines what is to be published and how it should appear.

Documents can be generated by selecting a Package or Element in the browser and then invoking the Document Generator (Function key F8).

Templates can be one of:

Normal
Fragment
Table of Contents
Cover Page
Style Sheet

Note: As mentioned above, Dynamic sections use a Template. This template can be:

Normal

Fragment

Table of Contents and Cover Page templates are not supported in a Custom Document.

A Style Sheet can be applied to the document represented by the Custom Document.

Content of the Custom Document

So that a valid comparison can be made between the existing Documentation Generation and a Custom Document, an example EA repository whose contents can be published using a Master / Model Document with a collection of defined templates will be used to determine the content of this Custom Document.

This example has the following structure:

And has the following templates defined:

Below is the Master / Model document model for the publication of Requirements Specification document:

The table below specifies the static and dynamic sections and where appropriate the package and template to be applied:

Static & Dynamic Sections for Custom Documents

This example repository also includes templates for:

Cover Page
Style Sheet including List Overrides

Cover Page

As a Custom Document does not support a Cover Page template, the content in this example will be created as Static content to the first static section in the table above. The content for this cover page will be that of the Cover Page Template as used in conjunction with the Master / Model document above.

This is shown below:

Note: The Report Constants shown above in shaded grey are NOT supported in a Custom Document and hence will be replaced by static text.

Style Sheets and List Overrides

Style sheets and list overrides are not supported directly by a Custom Document; however a style sheet can be applied to a Custom Document.

The most effective method to use a Style Sheet in a Custom Document is:

Create the Style Sheet and List Overrides (if required) alongside the Templates
Apply the Style Sheet to each template after it has been created and tested

Using the method above, when a dynamic section is added to a Custom Document the Style Sheet will be applied automatically to the template associated with the dynamic section.

Adding the Custom Document Element

The Custom Document element can be found in the toolbox of all diagram types in EA and does not have to be created on a diagram.

A Custom Document element is located in any package within the Browser, and in this example the following steps are used:

Open any diagram and show the Toolbox
Create a View / Package for the Custom Document element. In this example:

A View named Custom Documents is added to the *Model Root Node* named Documentation

Using the Documents section of the diagram toolbox, a Custom Document element is selected
The View created in step 2) above is the clicked in the Browser. EA then adds a Custom Document element to this View
Using F2 the Custom Document element is named Requirements Specification

Creating a Static Section

Static sections are added to the Custom Document using the Linked Document editor. For the first static section, the Linked Document editor has to be opened, using the following steps:

Double-click the Custom Document element created in the previous section
The following dialog is displayed:

A number of pre-defined templates are available on the drop-down list (these correspond to the templates for any Linked Document), although one of these could be chosen, it is usual to accept the default None and simply click OK. This will display the Linked Document editor and the Custom Document Content list:

To create a Static section text is simply added (or copied / pasted) to the document area. Text can be formatted using the controls in the Edit section. Tables can be added and formatted. Images can be inserted. This editor is the same as that used for creating a Documentation Template, except there are no sections
In this example, the Cover Page shown previously is re-created as a table in the Custom Document. This is achieved simply by:

Opening the Documentation Template called ECP – Cover Page
Selecting all the content
Copying to the clipboard
Pasting to the Custom Document

As a Custom Document does not support Report Constants (the items shaded grey above), these are replaced with text:

Note: The font for the style used for Version, Status, Date Generated and Author have been changed to Calibri.

The date is inserted by selecting Insert → Date and Time from the Insert menu and selecting a date format from those presented.

As this is a Cover Page, the last task is to insert a Page Break at the bottom of the table. A Page Break is inserted by selecting Insert Break → Page Break from the Insert menu
The remainder of the this static section is the same as the Documentation Template named ECP – Functional Requirements Heading. This can be opened, all text NOT the yellow shaded controls, copied to clipboard and pasted after the page break insert from the previous step:

Note how the style associated with the Documentation Template has been replicated in the Custom Document.

Creating a Dynamic Section

Dynamic sections are created by:

Selecting one or more items in the Browser
Dragging and dropping to the Custom Document
Selecting a Template to be applied to the dynamic section

In this example:

The packages corresponding to all Functional Requirements are selected in the Browser:

This select is dragged and dropped onto the Custom Document just below the static section just created
From the dialog that displays all the templates, these are filtered to User, the template named ECP – Requirements Catalog is selected:

Click OK and the dynamic sections (one per package) are created and formatted according to the template selected and the Content list is updated:

Save the Custom Document as you would for an EA Diagram

Completing the Content

Using the steps outlined in this article for creating Static and Dynamic content, the remainder of the document can be created:

Note: As you add Static / Dynamic Sections you may find that the paragraph numbers do not update. If so, simply, right-click the Custom Document and select Update Styles from the menu and select the appropriate Style Sheet.

In the above the Paragraph Marker or Pilcrow is shown (click the Paragraph Marker in the Edit ribbon).

This shows that a number of extra newlines have been added to the end of the document, you may, is you wish, delete the ones that are not required. BE CAREFUL not to delete the dynamic section!

Adding a Header / Footer

Headers and Footers are optional and can be added to a Custom Document in exactly the same was as for a Documentation Template.

In this example the following steps were used to add a Footer for the Page Number / Page Count:

Scroll to Page two (that is after the cover page, or the first Dynamic Section)
Click anywhere on this page
Select Page Header/Footer → Edit Page Header/Footer from the Edit menu
Click in the Footer Area
Insert a table consisting of one row and one column
Set the text alignment to Centre
Enter the Text Page followed by a space
Insert the page number by selecting Page Number from the Insert Menu
Enter the Text of surrounded by one space
Insert the page count by selected Page Count from the Insert Menu

Scrolling back to the Cover Page will reveal that the same footer has been applied, which is not required for this first page, therefore:

Click on this Page
Select Page Header/Footer → First Page Header/Footer → Create First Page Footer from the Edit menu
Click anywhere in the document

The steps above will remove the Footer from the first page. Save the document.

Exporting the Document

Now that the document is complete it can now be exported.

Select Save as (Export to File) from the File menu

Navigate to a suitable location
Choose the desired Save as type: (for example Word Document Format(.DOCX)
Enter a filename
Click Save

The document can now be viewed in MS Word.

Comparison with Master / Model Document

The main difference between Custom Document and a Master / Model Document, is that when changes are made to the repository, the Custom Document dynamic sections can be updated and changes to the document viewed directly in EA.

Using the Master / Model Document, the document would have be re-generated and opened in Word to view the changes.

WARNING!

It is possible to the entire Custom Document or just a single Dynamic Section. We have observed that when List Overrides are in use with a style sheet, then upon updating a Dynamic Sections, some newlines have the incorrect style. They are Heading-n rather Normal as shown below:

This can be rectified simply by clicking in the text that is incorrect (1.2 above) and changing the style to Normal.

If the whole document has been updated, then the entire document will have to be examined for this anomaly. If only a single dynamic section has been updated, then only this section needs examination.

Master / Model documents via the Documentation Generator allows the use of Report Constants whose values are taken from tagged values in the Master Document package.

Apart from Date/Time a Custom Document does not support Report Constants so plain text has to be used.

If the values for these changes, say the Status or Version then this text is updated manually in the static section of the Custom Document.

The same update would apply to the tagged values however, so in my opinion this is *not* a major issue.

Observations & Conclusion

This exercise proved valuable as a comparison between publishing using the EA Document Generator from a Master /Model document, and publishing from a Custom Document.

Observation #1: BOTH publishing methods require a full set of templates to be created before publishing, so this skill in EA is most definitely required
Observation #2: A Custom Document does not have the concept of Cover Page, but one can be created as a static section and copying and pasting from a Cover Page template
Observation #3: A custom document displays the finished document directly in EA which is a really good feature, however there do appear to be issues when dynamic sections are updated with regards to the wrong style being applied. Whether or not this is linked to List Overrides remains to be verified, but this issue is certainly something to be aware of
Observation #4: A custom document can be exported directly to HTML format. This option is not available using the Document Generator. This format maybe useful for EA users who for some reason do not have access to MS Word
Observation #5: Provided the same templates are used the document produced using a Custom Document, can be identical to that generated from a Master / Model document
Conclusion: Do I believe that Custom Documents are a direct replacement for a Master / Model document? No. I believe that both are useful features for publishing.

Do I believe that Custom Documents are complimentary to Master / Model documents? Absolutely. The live view of the document within EA is excellent, not withstanding the Warning noted in this article.

Finally, in my opinion, Custom Documents cannot be used without a series of Document Templates, so the EA skill of how to create these Templates is essential to publishing regardless of how the document (or documents) are published.