Title Guidelines

Keep these guidelines in mind when naming troubleshooting topics:

• Use title case
• Use nouns or noun phrases
• Include the issue or error

Examples: “DITA Open Toolkit Error DX931118”, “Flickering Screen”

Style Guidelines

Keep these guidelines in mind when creating troubleshooting topics:

• Document common or obscure problems and their remedies
• Include all possible remedies for the problem

Considerations

Ask yourself the following question when creating troubleshooting topics:

• Is this problem reproducible?
• Do I have all the required information for the situation?
• Is there any additional information required for the remedies?

Structure

troubleshooting topics can contain the following elements:

• troubleshooting element
  1. title element
  2. abstract element
     • short description element
  3. prolog element
  4. troublebody element
     1. condition element
     2. solution element
        1. cause element
        2. remedy 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.

troublebody element

The main element of a troubleshooting topic.

condition element

Illustrates the state that the troubleshooting topic should fix.

solution element

Contains a cause element and a remedy element.

cause element

Describes the source problem.

remedy element

Contains steps that provide a potential solution for the problem.

Troubleshooting Topic Example