Help System Authoring

HelpPackage

Each individual Help topic is defined by a «HelpPackage» element. This can be owned by a parent Package or HelpPackage, and can own child HelpPackages to form a hierarchy of topics providing general and then more detailed and specific information on some aspect of the system.

Each HelpPackage element contains one - and only one - HelpTopic element, which must have the same name as its parent HelpPackage.

HelpTopic

A «HelpTopic» element corresponds to an HTML page. The name of the HelpTopic element is rendered as the page title in any generated documents.  The HelpTopic 'Alias' property is used as the name of the .html file that the topic is generated to.

The HelpTopic element usually contains some introductory text to explain the purpose of the topic and how it fits into any topic structure of which it is a part.

There can only be one HelpTopic element in a HelpPackage. The HelpTopic can be the parent of other Help elements, except for:

• Other HelpTopics
• HelpTopicProxy elements
• HelpTableRows, and
• HelpTableRowProxy elements

HelpTopicProxy

If you want to duplicate an existing Help topic, you can add a «HelpTopicProxy» element to the HelpPackage instead of the HelpTopic element. You do not add any other elements under a HelpTopicProxy element, because it calls in the entire contents of the topic being duplicated.

HelpSection

A «HelpSection» element corresponds to one or more related paragraphs within a page, discussing a particular subject.

The name of the HelpSection element is rendered as a subheading within the document generated for the parent topic.

A HelpSection can only be a child of a HelpTopic, and cannot contain any other type of element, including other HelpSections. You can have many HelpSections under a HelpTopic, or one, or none.

A HelpSection element with the name Notes is usually placed second-to-last under the HelpTopic (before the Learn More section), containing a bullet list of additional points on the subject of the topic. However, it is not mandatory to have a Notes section.

HelpSectionProxy

A «HelpSectionProxy» element captures the contents of an existing HelpSection elsewhere in the system. You use this element to duplicate material in one or more other points in your Help structure. A HelpSectionProxy can only be a child of a HelpTopic, cannot contain any other type of element, and has no text content of its own.

HelpSectionDiagram

A «HelpSectionDiagram» element is used as a placeholder/container for a diagram that will appear in the Help as an image. The diagram should be created as a child of the HelpSectionDiagram element; any (non Help) elements or constructs used to create the diagram will not appear in the HTML or PDF documents themselves.

The diagram in this element is usually a stand-alone diagram that illustrates the topic as a whole. You can also create links within a HelpTopic, HelpSection or HelpTableRow to show diagram images that illustrate a specific point.

HelpSystemVideo

A «HelpSystemVideo» element is used as a container for a video control, which will play a video within the web browser in which the Help is being viewed. This allows for the inclusion of short 'How To' videos from your website, which can be viewed 'within' the User Guide.

HelpSlideshow

A «HelpSlideshow» element is used as a container for a slide show control, which will play a sequence of slides within the web browser in which the Help is being viewed. This allows for the inclusion of 'What this feature looks like' slides on your website, which can be viewed 'within' the User Guide.

HelpTable

A «HelpTablexn» defines one of several types of table according to the actual stereotype selected.  The HelpTable identifies the number of columns, the relative column widths and, in Tagged Values, the column headers. The different types of table are described in the Help Systems Tables Help topic. The Help Table can have any number of child HelpTableRow or HelpTableRowProxy elements.

The name of the HelpTable element is rendered as a heading above the table in any gererated documents.

HelpTableProxy

A «HelpTableProxy» element captures the contents of an existing HelpTable of any type elsewhere in the system. You use this element to duplicate material in one or more other points in your Help structure. A HelpTableProxy can only be a child of a HelpTopic, cannot contain any other type of element, and has no content of its own.

HelpTableRow

A «HelpTableRow» element defines the content of a single row of a table of any type. The element name is the row title, and the Notes for the element provide the description or explanation of the row title. Tagged Values define the hyperlinks to supporting Help topics, in the 'See also' column. If the table does not support a 'See also' column, those Tagged Values are ignored.

A HelpTableRow can only be a child of a HelpTable, and cannot contain any other type of element.

You can also use Tagged Values to add an icon to the row header, or to replace the header text with an icon. This is discussed in the Use of the Help System Elements Help topic.

HelpTableRowProxy

A «HelpTableRowProxy» element captures the contents of an existing HelpTableRow elsewhere in the system. You use this element to duplicate material in one or more other points in your Help structure. A HelpTableRowProxy can only be a child of a HelpTable, cannot contain any other type of element, and has no content of its own.

HelpSectionLearnMore

The «HelpSectionLearnMore» element is used to provide a list of hyperlinks to related topics that have not been linked elsewhere in the topic, nor in the Help hierarchy displayed next to the generated Help topic. It is usually placed at the end of the topic so as not to distract from the material presented in the body of the topic. The element name is always 'Learn more'; there is only one 'Learn more' section under a HelpTopic, and it cannot have any child elements.

The PDF generator ignores this element.