Title Guidelines

• Use title case
• Begin with an infinitive

Examples: “Set Up a Virtual Machine”, “Develop a Course”

Style Guidelines

• Depending on the information architecture of your documentation, you may use the following approaches to develop process topics:
  • Collection-type approach. See Collection-Type Approach to Processes.
  • Cross-reference approach. See Cross-Reference Approach to Processes.
• Differentiate process topics from task topics by assigning a dedicated attribute to their task element root tags.
  Tip: For example, you can set the process value to the outputclass attribute. Then, you can set the publishing plugin to render the process topics in a desired way

Structure

process 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.