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>
. The
<troubleshooting>
element contains a
<title>
with optional alternative titles
(<titlealts>
), a short description or
<abstract>
, a <prolog>
, a
<troublebody>
, and
<related-links>
.
<troublebody>
is the main body element in a troubleshooting
topic. The <troublebody>
element contains the following
elements:
<condition>
<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>
<troubleSolution>
elements must appear in the
<troublebody>
element.
<troubleSolution>
is a wrapper element for
<cause>
and <remedy>
, each
of which are a cause-remedy pair. The <troubleSolution>
element contains the following elements:
<cause>
<condition>
<troubleSolution>
describes a possible cause for the
condition. <remedy>
This optional, repeatable, last-child of
<troubleSolution>
describes a possible remedy
for the condition.
The <remedy>
element begins with an optional
<title>
element followed by an optional
<responsibleParty>
element followed by either
a <steps>
element, a
<steps-unordered>
element, or a
<steps-informal>
element. The content models
for <steps>
,
<steps-unordered>
, and
<steps-informal>
are borrowed from
<task>
. This allows remedy to reuse steps
from tasks.
<remedy>
indicates who
is expected to perform the steps that are outlined in the
<remedy>
element.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>