The troubleshooting topic type provides markup for corrective action information such as troubleshooting and alarm clearing.
In its simplest form, troubleshooting information follows this pattern:
The troubleshooting topic provides sections for describing the condition, causes, and remedies needed to restore a system, a product, or a service to normal.
For some conditions there could be more than one cause-remedy pair. The troubleshooting topic accommodates this. Typically, a cause is immediately followed by its remedy. Multiple cause-remedy pairs can provide a series of successive fall-backs for resolving a condition.
Cause and remedy might occur in combinations other than pairs. It is possible to have:
The troubleshooting information type also can be used to document alarm clearing strategies.
The top-level element for troubleshooting topics is
<troubleshooting> element contains a
<title> with optional alternative titles
<titlealts>), a short description or
<troublebody> is the main body element in a troubleshooting
<troublebody> element contains the following
<troublebody>, and it describes a condition or symptom that is associated with an undesirable state in a system, a product, or a service. In cases where the topic title fully explains the condition, do not use this element.
<troubleSolution>elements must appear in the
<troubleSolution>is a wrapper element for
<remedy>, each of which are a cause-remedy pair.
<troubleSolution> element contains the following elements:
<troubleSolution>describes a possible cause for the condition.
<troubleSolution>describes a possible remedy for the condition.
<remedy> element begins with an optional
<title> element followed by an optional
<responsibleParty> element followed by either
<steps> element, a
<steps-unordered> element, or a
<steps-informal> element. The content models
<steps-informal> are borrowed from
<task>. This allows remedy to reuse steps
<remedy>indicates who is expected to perform the steps that are outlined in the
Here is an example of a troubleshooting topic:
<troubleshooting id="nologon"> <title>Cannot log on</title> <shortdesc>Login attempts have failed</shortdesc> <troublebody> <condition> <p>The system does not accept your login credentials.</p> </condition> <troubleSolution> <cause> <p>The CapsLock key might be on.</p> </cause> <remedy><steps-unordered> <step> <cmd>Verify that the CapsLock key is off.</cmd> </step> </steps-unordered> </remedy> </troubleSolution> <troubleSolution> <cause> <title>Wrong password</title> <p>The password that you are using does not match the one that is stored in the system.</p> </cause> <remedy id="gotoaccountmanagement"> <steps> <step> <cmd>Open a Web browser window</cmd> </step> <step> <cmd>Go to <xref href="http://itdept.example.com/reset.html" format="html" scope="external"> Account management</xref>, and follow the instructions</cmd> </step> </steps> </remedy> </troubleSolution> <troubleSolution> <cause> <title>Unknown account name</title> <p>The account name you are using does not match the one stored in the system.</p> </cause> <remedy conref="#nologon/gotoaccountmanagement"/> </troubleSolution> <troubleSolution> <remedy> <title>Still cannot log on</title> <steps-informal> <p>If none of the previous solutions work, consider asking for help. Contact your system administrator if your organization has one; otherwise, contact our support team.</p> </steps-informal> </remedy> </troubleSolution> </troublebody> </troubleshooting>
Return to main page.
Standards Track Work Product
|Copyright © OASIS Open 2016. All Rights Reserved.||25 October 2016|