Authoring Help System Content

The Enterprise Architect Help System model provides all the structure, formatting and styles you require to immediately create and generate Help topics that resemble the Enterprise Architect Help itself. You can then edit the CSS file and the templates to tailor the output to reflect your organizations own standards and presentation.

The format of the source Help material is largely controlled by Enterprise Architect, and then interpreted by the HTML and PDF generators as defined by the templates and CSS file. There are, however, various formats and styles you can impose as you write your Help text, and these are discussed in the sections of this topic.

Using the Specification Manager

The primary tool for authoring help content is the Specification Manager. This is a customizable 'document like' interface into which you can add and author Help content. To open the Specification Manager, select a HelpPackage in the Browser window, then either:

• Press Ctrl+0
• Right-click and select Specification Manager, or
• Select the Design > Package > Specification View ribbon option.

Thereafter, when you click on a Help element in the Browser Window, the Specification Manager changes focus to the parent HelpTopic for that element.

The Specification Manager has a number of columns that help you check and maintain properties of a Help element, such as Status, Priority and Stereotype. You might also prefer to hide all the columns except for 'Item', which will just show the element name and Notes content (the Help text). You use the 'Field Chooser' context menu option to add columns, and simply drag column headers out of the header bar to hide them.

When you open the Specification Manager, the Specification-Specify ribbon automatically displays. Useful options in the ribbon include:

• 'Element > Insert > Show Toolbox' - displays the Diagram Toolbox, which you can pin to the Help System page so that it always opens at that page.
• 'Element > Move Up' and 'Element > Move Down', which help you re-order the sequence of peer-level elements
• 'Display > Notes Format', which enables you to put the Notes text where it best suits you to read and edit it, either underneath the Help element name or to the right of it, or to hide the column headings ('Document View')
• 'Display > Level Numbering', which - in more complex topic structures - numbers parent and child elements so that you can see which elements are children of which parents
• Display > Bold Names', to bolden the element names and make them more visible in amongst the blocks of text
• 'Display > Collapsible Regions' to hide child elements underneath their parent elements, so that you can expand only the element group you want to work on (very useful when you have a number of tables, especially with many rows)
• 'Display > Font Size', which allows you to change the display size of all text to make it easier to read, or to include more text within the window area

The Notes window

The second important window for developing Help text is the Notes window, which makes it a bit easier to do formatting and hyperlinks through the Notes window toolbar options.

Some useful shortcuts in notes are:

• Ctrl+. Starts or ends a bulleted list
• Ctrl+0 Starts or ends a numbered list
• Ctrl+B Set Bold on or off
• Ctrl+I Set italics on or off
• Ctrl+U Set underline on or off

Referencing Images

Using images in the Specification Manager is achieved by using the normal Notes window. To link to an image open the Notes window and use the Hyperlink toolbar button to add a hyperlink to an image in the Image Manager (select the hyperlink type as 'Image Manager'), or as an Image Asset held in a reference diagram (select the hyperlink type as 'Element Image').  It is also possible to add a Hyperlink directly to a diagram held in the same project (select the hyperlink type as 'Diagram Image').

Style and Formatting Considerations

As you will be editing a document that will later be generated, most of the formatting and style considerations are already handled automatically at generation time. Try to avoid manually applying bold, italics, underline or color to text. Instead use the Glossary to consistently markup terms by category (see the later section on the glossary).

Where a HelpSection or HelpTable contains a lot of code, you might prefer to format the text in monospace. You can do this by selecting the 'Tags' tab of the Properties window for the element and adding a new Tagged Value 'ContentType' with the value 'basic'.

The Role of the Glossary

As you add content you might see some terms underlined; this is because they are defined in the glossary and will appear in the final Help document with a special color or appearance. If you are including new terms for user interface elements, hot keys or special terms, it might be that you should add them to the appropriate section in the glossary. You can do this by highlighting the term and using the context menu to Create | Glossary Definition. Add the term to the appropriate place and check your generated content to ensure it appears as expected.

The Model Glossary also plays a part in defining the native language in which you write the Help text, and any other language you translate it into. See the Translation Facility Help topics.