It’s a fair bet that the introduction of the new Troubleshooting information type into the DITA 1.3 technical authoring standard will affect how all Technical Authors write troubleshooting topics, regardless of whether they use DITA or not. That’s because the proposed elements for troubleshooting topics make good sense, and it offers a standardised approach to writing these types of topics.
According to the Oasis DITA standards committee,
Troubleshooting topics provide descriptions of and solutions or workarounds for problem situations that users might encounter. Users refer to troubleshooting information to understand what condition or event generated their problem situation and to find out what they need to do to recover from or work around a problem, or to prevent a recurrence of the problem.
The user would see a topic that looks roughly like this:
Application is not responding
Overview
This topic explains what to do if the application is not responding to your keyboard or mouse.
The problem
The application does not respond to input from the keyboard or the mouse.
The cause
The application has entered into a state from which it cannot recover.
Remedy
- Right-click on the Windows task bar and select Task Manager.
- Right-click on the application and select End Task.
The application should now respond correctly. If it does not, please contact the Support desk.
Responsible party
Users must fix this problem.
Related topics
See also:
- Adding a widget
You’ll notice there are a set of common headings:
| Section | Description | Example |
|---|---|---|
| Topic Title | A brief statement of the problem. | Application is not responding. |
| Overview/Introduction | A fuller explanation of the purpose of the procedure and when you would use it. | This topic explains what to do if the application is not responding to your keyboard or mouse. |
| Condition (the problem) | Usually the condition or symptom is an undesirable state in a system, a product, or a service that a reader may wish to correct. |
The application does not respond to input from the keyboard or the mouse. |
| Cause | A cause for the condition or symptom. | The application has entered into a state from which it cannot recover |
| Remedy (Solution) | A remedy for the condition or symptom that restores the system, product, or service to its normal state.The step-by-step instructions that explain how to actually do the procedure.Steps begin with an action statement that tells the user what to do. Every action statement contains a “command” verb.A step may also contain a feedback statement. This tells the user what happens as a result of completing the step. |
|
| Responsible Party | Who is expected to perform the steps in the remedy. | Users must fix this problem. |
| See also | Links to related topics. | See also:
Adding a widget |
We think the proposed structure is good, and it’s worth adopting. What do you think?
Re. Overview/Introduction
IMHO too generic. May invite tech authors to write long stories or repeat the title.
Proposed solution: “Short Description”. Dita authors are familiar with Short Desc and guidelines for writing _good, meaningful_ Short Descriptions are available (s. Kirsten Eberlein and Michelle Carey)
You’re right that writers following DITA 1.3 standard will use ShortDesc instead of Overview or Introduction.
For writers not using DITA, and for users, both of whom are unlikely to understand the phrase Short Description, Overview or Introduction is probably a more meaningful phrase to use.
You have necessarily used a simple example with a single symptom and a single solution. I wonder how well it will work for a less well defined problem like “The system is slow to respond” or “Some of my messages don’t always get delivered”, where some real investigation is required to pin down exactly what has gone wrong and what course or courses of action are likely to alleviate the problem. I guess that will depend to some extent on how flexible the “Remedy” element is. From the example it looks as if it contains , so it probably also allows , but will it allow generic text in or tags?
In the scenario you posed, it would probably be better to use the concept information type, perhaps linked to other to tasks or a list of potential troubleshooting remedies.