Proposed Troubleshooting Template

The following describes how we can mock up a new information type to describe troubleshooting issues.

Structure / Include / DITA Base / Sample Text
TITLE: Meaningful descriptive title for the Issue / Required / Title /

Older widget doesn’t work after downgrade

PREVENTION: Can be used as an admonition for relevant tasks / Recommended / ShortDesc / Never attempt to install the widget 98 or older with the Whatzit 3000.
ENVIRONMENT: Describes the conditions in which the issue is most normally encountered / Optional / Body / You may encounter this issue if you are using the North American model of the Whatzit 3000 and are attempting to downgrade or reinstall a legacy widget.
European and Asian models are not impacted.
CAUSES: Describes the background of the issue / Optional / The North American Whatzit 3000 uses the standard UTY protocol that may cause problems with older widgets using PPIP protocols for lorem ipsum ad velorum.
SYMPTOMS: Describe the error condition and will include error messages to help diagnose the error / Recommended / You may experience any of the following symptoms if you attempt to install the older widget with the Whatzit 3000:
·  Widget fails to work
·  Widget works intermittently
·  The Whatzit 3000 accessory panel displays the following error message
o  BUZZ201: Legacy widget failed to start
RESOLUTION: List options for resolving the issue / Optional / To restart your widget we recommend that you try
·  Reinstalling an older version of the Whatzit
·  Installing a third-party UTY adapter
·  Replacing the legacy widget with a newer UTY type accessory
RELATED TOPICS: Lists Diagnostic Tasks, Corrective Procedures, and related trouble-shooting issues. / Optional / Related Topics / Related Information
Diagnostic Procedures
·  Run widget power test
Corrective Procedures
·  Install UTY adapter
·  Replace legacy widget

This model is supported by other information types including concepts, definitions, diagnostic tasks, resolution tasks, and other related troubleshooting information (parent, child, or sibling). This information type is informed by a larger content metamodel I have been working on for enterprise information.

A subset of this same information may be reused with just the title, prevention, and symptoms in some publishables such as FAQs and Quick Reference.

This roughs out the main semantic sub-structure of the information type. There would be some additional semantic markup within each of these sections to provide for author guidance and reuse opportunities. In particular, we could capture the error messages in this topic type or conref them from reference topics. The symptoms are a very important semantic element that will allow us to group and sort this information in different meaningful ways.

This is based in part on work performed in the BusDocs subcommittee in OASIS and the IBM troubleshooting specialization. The main differences between the IBM specialization include:

·  All task and role information is removed from the IBM specialization

·  A critical Preventative statement is added to the IBM specialization

·  The order of the body elements is slightly different but otherwise very similar.

A more generalized version of this information type (Governance) that we’ve developed in the subcommittee can be used for

·  Policy Information

·  Guidelines and Practices

·  Hazard Statements

·  Legal and Legislative Information