Process Topic
Use process topics to organize multiple task topics into a cohesive set of instructions.
Process topics answer the following question: “How do I do x?”
Title Guidelines
- Use title case
- Begin with an imperative
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
- title element
- abstract element
- short description element
- prolog element
- task body element
- prerequisite element
- context element
- steps element
- step element
- command element
- information element
- step example element
- choices element
- substeps element
- step result element
- step element
- result element
- 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.
Collection-Type Approach to Processes
Processes created by adjusting the collection-type attribute are easy to create and maintain.
Linking created by adjusting the collection-type attribute is compatible with the DITA Open Toolkit (DITA-OT) publishing scenarios with the args.rellinks parameter set to all, and Heretto Portal publishing. It is not compatible with Heretto PDF Generator publishing.
Considerations
Keep in mind the following advantages of process topics using the collection-type attribute:
- Easy to create and maintain. If the number or order of procedures appended to a process topic change, the process topic list updates automatically.
- Reflects the topics' hierarchy in a map.
Keep in mind the following limitations of process topics using the collection-type attribute value:
- You cannot manually add additional information to the process topic steps, as they are generated automatically.
- You cannot append the same procedure under multiple process topics in the same map.
- Your DITA Open Toolkit publishing scenarios may require configuration to render the process topic steps as expected.
Example
Cross-Reference Approach to Processes
Processes that use cross-references are flexible but may become hard to maintain.
Considerations
Keep in mind the following advantages of process topics that use cross-references:
- You can add additional information to the process list. For example, you can add note elements or mark process step elements as optional.
- You can link to the same task topic (procedure) from multiple process topics in a map.
- Compatible with a variety of publishing engines and publishing scenarios.
Keep in mind the following limitations of process topics that use cross-references:
- The process topic steps are not generated automatically so you need to add them manually.
- Cross-referenced content can be hard to maintain. The process topic steps do not update automatically when the number or order of task topics (procedures) changes.
- Topic hierarchy may not always be reflected, as the task topics (procedures) do not need to be appended under the process topic.