DT Consulting Newsletter Issue 2


This second newsletter describes a technique to produce customized documentation if RTF format in Enterprise Architect. 

Producing Customized Documentation

The most common method of producing customizing RTF documentation in Enterprise Architect is:
1) Modify or create a template detailing what will appear in the documentation
2) Create one of more Virtual Documents to control which packages will appear and the order in which they will appear
These techniques are well known but suffer from the following limitations:
1) The formatting features in the RFT template editor are rather limited, especially with numbered and bulleted lists, headers and footers.
2) The “iterators” that produce the content con only be used once within a template. So it is not possible to obtain a summary of elements, followed by their details.
3) It is not possible import or use a template defined in Word.
The most common work around to these issues is to create a master document in Word which contains the necessary format and import the resultant RTF documents. This works just fine, but does not overcome issue 2 above. The remainder of this newsletter details an interesting method of solving all issues above. The technique is known as RTF Bookmarks.

RTF Bookmarks

Each item in the Project Browser (that is a View, Package, Diagram or Element) has a unique RTF Bookmark and this can be used when importing RFT Documents into Word. Instead of importing the complete RTF file, a range can be specified. This range is the RTF bookmark. This means that a section of a RTF document can be imported in a Word document where you like and as many times as you like. These imports can be made into links, so that when the underlying RTF document changes, the Word document can be updated to reflect these changes.
This technique is a little laborious to set up, but once this has been achieved you will have a very flexible document. The method is as follows:
1) Create a Word document that is formatted to your requirements, with Headers, Footers, and styles
2) Create a customized RFT template, or templates
3) Generate the RTF documentation
4) Decide on what is to be inserted into the Word document
5) Find that item in the Project Browser and copy its RTF Bookmark to the clipboard
6) Insert the RTF document into work using the RTF Bookmark as a link
7) Repeat the process for all desired items.
8) Format the Word document adding headers, tables etc

A Worked Example

As an example of this process, let’s assume that we wish to create a Word document that has company branded headers and footers and is to document the following:
1) Textual description of the system
2) Summary listing of Actors and Use Cases in a Table
3) Detail of each Actor
4) Detail of each Use Case
5) The Use Case Diagrams

Step 1

Create the following customized RTF templates:
1) A template to output the names of all elements (including child elements and embedded elements), you may elect to filter out “anonymous elements”
2) One template that outputs a single detail for all elements (for example the notes)
3) One template that outputs all the diagrams in the project
The reason the large number of templates, is that if all detail is contained within a single RTF document, the text that is not wanted can simply be cut from the Word document, but when the Word document links are updated all the unwanted text is restored!

Step 2

Produce the RTF documents.

Step 3

Create a formatted Word document containing the company branded headers and footers plus any other formatting styles required. 

Step 4

To create the Actor and Use Case Summary:
1) Copy the RTF Bookmark for an Actor to the clipboard and use this a range when inserting the RTF document into Word (use the RTF document just containing the names of elements)
2) Repeat for all Actors in the sequence desired
3) Repeat the process for all Use Cases.
4) Note that in the process above, if an element has children or embedded elements, the detail of those children will be pasted into Word along with the parent element.
5) Format the output text that has been inserted accordingly, be careful that when moving the inserted text to ensure that the field is still “updateable” (check by right clicking the field). It may even be easier to insert the RTF bookmarks in the formatted text so as to preserve the links

Step 5

To produce the remainder of the documentation, proceed in a similar manner to above

Updating the Links

As the links to the underlying RTF documents are “live” these are supposed to be updated when the Word document is re-loaded, however this does not appear to work. Word does have a function to view and update all links, the method on how this achieved is dependent upon the version of Word in use.

The Results

At the end of this newsletter is an example of the kind of documentation that can be produced with some time and effort. This is only the early stages of such a document, but I hope that it inspires you to have a go at using RTF bookmarks when generating your documentation.

On-Line Store System

This document describes the design of a simple on-line shopping system, where Members of the Public can browse an on-line catalogue of items and create shopping carts of those items. More than one shopping cart can be created, but only one can be active at any one time.
The active shopping cart can be saved for later or checked out. Payment is accepted via Credit or Debit card and these are verified using an external credit authorisation service.
Successful check outs result in an order being created and the items begin shipped to the Member of the Public.
Actors and Use Cases
This section summarises the Actors and Use Cases in the system

Actor Detail

Previous Next