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
This topic explains what to do if the application is not responding to your keyboard or mouse.
The application does not respond to input from the keyboard or the mouse.
The application has entered into a state from which it cannot recover.
- 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.
Users must fix this problem.
- Adding a widget
You’ll notice there are a set of common headings:
|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?