Topic with an optional image and table

Structured Authoring

The following sample structure is for a topic that will validate with or without a screenshot that has an accompanying table with descriptions. The Group rule is used to create a sub structure around the rules for the image and the table, and assign the attributes that make this block of content optional.

The content rules for this example define the types of paragraphs, the image and table, and the paragraph level formatting. Validation is based on the layout of the topic (the types of paragraph content and where they are used) and the paragraph level formatting.

Validating content when a variable number of occurrences has been allowed in a rule

When you are allowing the author to use a variable number of paragraphs you need to consider the paragraph styles allowed by different rules. If the same paragraph style is allowed by different paragraph rules and the author has not used a rule to its maximum number of occurrences, validation may use a rule that the author does not expect. This is because validation tries to match all possible instances of a rule to content before checking validation for the next rule in the structure.

For example, validation could be affected in this topic if the additional paragraphs rule and the image rule both use Body Text and the author has not used the maximum number of occurrences of the "additional paragraph". This is because both rules use the Body Text style and both rules allow the use of images. In this example validation attempts to match the remaining occurrences of the "additional paragraph" rule to the "image paragraph" and this could result in correct content being shown as invalid.

Content or style guide rules for the procedure topic

  • The topic must have an opening paragraph to describe the product functionality.
  • Where necessary one screenshot of the product can be added to the topic. The screenshot must always be based on the Embedded JPG File template.
  • If the screenshot requires further description add numbered callouts. Do not add text callouts directly to the image.
  • When the screenshot requires callouts use a two column table for the information. When the table is used it is always added after the image. The first column is used to display an image of the numbered callout. The second column is used for the description. The table is formatted using the Table Body Text style.
  • When a screenshot is added to the topic nothing else should be added to that paragraph (for example, ordinary text should not be added to a paragraph containing a screenshot.)
  • Additional text paragraphs can be added to the topic either before or after the screenshot (or screenshot and table).

Structure rules

Group Rule Optional Screenshot and Table

  • Rule 1: Opening Paragraph Rule

    Allow one paragraph. Location sequence is Fixed - must be used at the start of the topic. Allowed style - Body Text.

  • Rule 2: Additional Paragraphs Rule

    Use of additional paragraphs is optional, allow a maximum of five additional paragraphs. Location sequence is Flexible - must be used after the opening paragraph, but the order can be swapped with the Group rule. The rules can be swapped because the paragraph and group rules are both flexible and are adjacent in the structure. Allowed style - Body Text.

  • Rule 3: Group Rule - Screenshot and Table

    Optional, but a maximum of two occurrences of the image and table group are allowed. Location sequence is Flexible - must be after the opening paragraph but can be swapped with the Additional Paragraphs rule.

  • Rule 4: Paragraph Style Rule - Wide Graphic

    Applies the formatting to the paragraph containing the screenshot. Once occurrence is allowed. Location is Fixed - when the rule is used the paragraph for the screenshot must be used before the table. Allowed styles - Wide Graphics.

  • Rule 5: Screenshot Rule

    When rule is used one screenshot must be added. Location is Fixed - the screenshot must be the first child content in the paragraph (see note). Allowed object - Embedded JPG File Template (any image can be used, or new images can be created, so long as the File object is based on this template).

    Note: The Paragraph rule only contains the File rule, no other child rules have been created. When inline content does not have a child rule there are no restrictions placed on its use. This paragraph would still validate if any of the other forms of inline content were added (variables, hyperlinks, and so on). The style guide rules should be used to ensure authors don't add extra content to the paragraph.

  • Rule 6: Table Rule - Callout Text

    The table is optional, but if used a maximum of one occurrence is allowed in the topic. Location sequence is Fixed - when used it must be added after the image.

  • Rule 7: All Rows Rule

    The All Rows rule determines the formatting that will be applied to cells in all of the rows in the table. The attributes are applied using the Table Rule Type option of All Rows.

  • Rule 8: Table Body Text Rule

    Allowed style for the table formatting - Table Body Text.

The topic

Based on the structure rules any of the layout options are available and will all validate. The content in each of the samples is marked with the rules used for validation. Based on the rules, if you created a topic and added a table above the image the topic would not validate.

Topic with Group rule for image and table