Title Guidelines

• Use title case
• Begin with an infinitive

Examples: “Create an Assignment”, “Reassign a Project”

Style Guidelines

• Communicate each step clearly.
• Only include information relevant to completing a step.
• If the expected result needs some explanation, describe it in the step result element.
• Only include images or screenshots for steps where the interface changes as a result of the step, and it's relevant to illustrate this change to our users. Otherwise, avoid using images and screenshots due to high maintenance costs.
  • To provide a screenshot of the interface during the step, use the information element.
  • To provide a screenshot of the interface with completed fields or selections, use the step example element.
  • To provide a screenshot of the interface after completing the step, use the step result element.

Considerations

Ask yourself the following questions when creating task topics:

• What information is required to complete each step in the task?
• What background information does a user need to get started on the task?
• Would images or examples help clarify how to complete the procedure?
• What is the expected result of completing the procedure?

Structure

task topics can contain the following elements:

• task element
  1. title element
  2. abstract element
     • short description element
  3. prolog element
  4. task body element
     1. prerequisite element
     2. context element
     3. steps element
        • step element
          1. command element
          2. information element
          3. step example element
          4. choices element
          5. substeps element
          6. step result element
     4. result element
     5. postrequisite element

Elements

title element

Entitles a topic, a section, or a container element.

abstract element

Provides introductory content that would be unfit for a short description element.

short description element

Illustrates the topic purpose in two or three sentences (no more than 50 words). short description elements can provide content for link previews and search engines.

prolog element

Contains topic metadata. Can contain multiple resource ID elements that you can use to implement context-sensitive help into applications.

task body element

The main element of a task topic or a process topic.

prerequisite element

Describes the requirements that must be met before beginning a procedure.

context element

Provides brief background information for a procedure.

steps element

Contains step elements needed to complete a procedure.

step element

Contains a command element that describes an action and other elements that help you perform the action. To ensure optimal readability of your procedures, limit the number of step elements to 10 per one task topic.

command element

Describes an action that must be completed. We recommend using a single, unambiguous, and imperative sentence in each command element.

information element

Clarifies a step or provides additional information about a step. You can use the information element to add a figure element, code block element, or note element.

step example element

Provides an example on how to perform a step.

substeps element

Contains substep elements required to complete a step.

choices element

Provides different options to complete a given step. Each choice element encapsulates a single option.

step result element

Describes the expected step outcome.

result element

Describes the expected task topic outcome.

postrequisite element

Describes requirements that a user must meet after completing the procedure.

Task Topic Example