Technical documentation: Analyse the need for troubleshooting information and define the correct troubleshooting type adapted to a user-friendly error recovery. (full DITA XML compliant)

2. Keep calm
&
design your
troubleshooting topic
CMS DITA Europe conference
Munich, November 2015

3. Overview
• Authors & troubleshooting sections
• Experts recommendations
• DITA solution

4. Authors: play w/
« troubleshooting » messages

5. Authors: troubleshooting
variants

6. Authors: Troubleshooting
short form
https://medium.com/@thomasfuchs/how-to-write-an-error-message-883718173322

7. Authors: Troubleshooting
bla-bla

8. Authors: Troubleshooting
salad…

9. Authors: make it short
• Do these messages HELP the end-user
solve his problem ?

10. Authors: Puzzling
• Length
• long, short?
• Type
• Error messages?
• Descriptions?
• Questions?

11. Experts: « Butchering »
troubleshooting salad (*)
• Let’s listen to experts
• Let’s butcher the garbage
• Let’s focus on the user’s
needs
(*) produced by authors

12. Experts knowledgeable
about troubleshooting
• Information developers recognize that a high percentage of users
seek information only when they experience a problem. (*)
• However, most manuals “pose formidable obstacles to finding
problem-solving information.” (*)
• A Troubleshooting guide is probably the only guide users want
because it is really useful
(*) JoAnn Hackos in DITA-XML.org

13. Experts & error handling support
Supporting error handling is
uncommon, very uncommon
Results from an inventory study of 100 manuals:
• 33% gave NO support at all
• 50% present but not mentioned in TOC or index
• 86% not clearly visible as such in the text
(Dr. Hans van der Meij, Error-Information in tutorial
documentation)

14. Troubleshooting: why bother?
• Users: 25% time dealing with errors
• Presence of error information in the manual:
users perform better
• Objectives:
• Error recovery
• Help the user to go back to the previous situation
(Dr. Hans van der Meij, « Error-information in tutorial documentation »)

15. How much information?
• « Our research suggests there should
be ample error information in the
manual »
More information?
minimalism?

16. Experts advice (recap)
• User + problems= opens
manual
• 25% time= handling errors
• Problem= finding solution
• Error support= not visible
• Supporting error
handling= uncommon
• Ample error info is
needed (*)
• Objective= help user
recover from error
• Troubleshooting guide=
most important
(*) length of trbl. Info?

17. Troubleshooting history?

18. Elements of troubleshooting
information
• Error recognition / detection
• User to understand there is a mistake
• Message « Printer not selected »
• Title « Printer won’t start »
• Error diagnosis
• Nature of the mistake
• Action that caused the mistake
• Error correction
• Select a corrective method
• Recover (user wants to get out of…)

19. DITA 1.3
• Create well-structured troubleshooting topics
• Add troubleshooting items to steps and tasks
• Add troubleshooting notes to any topic
Dr. JoAnn Hackos (Chair, OASIS DITA Adoption TC)
Kris Eberlein (Chair, OASIS DITA Technical Committee)

20. Modeling
<troubleshooting>
<title>
<condition>
<cause>
<remedy>
Error detection
Pre-diagnosis
Diagnosis
Correction

21. Modeling (DITA 1.3)
<troubleshooting>
<title>
<shortdesc>
<prolog>
<troublebody> <condition>
<troubleSolution>
<cause>
<remedy>

22. DITA 1.3:
the troubleshooting types
1. Simple troubleshooting information
2. Complex troubleshooting information
3. Embedded troubleshooting
4. Troubleshooting note

23. Simple Troubleshooting
• Title
• Condition (situation when the error occurs)
• Cause (of the symptom)
• Remedy (to restore the system)

24. Simple troubleshooting -
(poor) Example
1.1 Blocked MMS Workstation
In case of a blocked MMS workstation the workstation shall be rebooted.
MMS Reboot:
1. Press “Ctrl-Alt-Del”
2. Click “Log off”
3. Confirm “Log off”
4. When prompted insert:
a. User name: . . . . . . .
b. Password: . . . . . . . .
The User Name and Password are provided in the latest version of document:
SC-OM.SO.PROC.PWD, Reference ID: BVCS-A
NOTE:
After the reboot, the “Alarm Viewer” application shall be restarted as described in section XXX

25. Procedure or
Troubleshooting ?...
1.1 Blocked MMS Workstation
In case of a blocked MMS workstation the workstation shall be rebooted.
MMS Reboot:
1. Press “Ctrl-Alt-Del”
2. Click “Log off”
3. Confirm “Log off”
4. When prompted insert:
a. User name: . . . . . . .
b. Password: . . . . . . . .
The User Name and Password are provided in the latest version of document:
SC-OM.SO.PROC.PWD, Reference ID: BVCS-A
NOTE:
After the reboot, the “Alarm Viewer” application shall be restarted as described in section XXX
Title ?
Note or
instructions?

26. Simple Troubleshooting (DITA 1.3)
<title> MMS Workstation is blocked
<shortdesc> If the workstation is blocked, an incorrect
action occurred in the process. Instead of
undoing steps, consider rebooting the
workstation.
<troublebody>
<condition> The workstation is plugged in, the power
switch is on, but the workstation will not start.
<troublesolution>
<cause> An incorrect action has interfered with the
normal boot process.
<remedy>
1. Press CTRL-ALT-DEL
2. Click “Log off”
3. Confirm “Log off”
Etc…
6. Restart the “Alarm Viewer”

27. <title>
• Title should match the most likely way
a user would describe the problem
• User’s terminology
• Add <indexterms> to provide search
options

28. Title and Short Description
• <title> Heading format
• Clearly describes the problem in the
user’s language
• Noun string that captures critical
information
• Use the exact error message:
<title> Error 31: Feature not found

29. Short description
• Useful in case of complex
troubleshooting information:
• Multiple solutions
• ShortDesc informs about the various
solutions

30. Simple Troubleshooting :
Short Description?
<title> System will not start
<shortdesc> If the system does not start, the circuit breaker may have tripped. A
qualified professional should reset the circuit breaker.
<condition> The system is plugged in, the power switch is on, but the system will
not start.
<cause> Power is not supplied to the system through the electrical outlet. A
circuit breaker has probably been tripped that blocks power
distribution.
<solution> 1. Make sure you have the necessary skills to reset the circuit
breakers.
2. Turn the system power switch to OFF.
3. Reset the breaker.
3. Turn the system power switch on ON.

31. Simple troubleshooting
(example)

32. Simple troubleshooting
(example)
<title> Blocked Rack
<condition> The rack is blocked on the rotative tray. The instrument
is still working.
<cause> A sample moved out of its place in the carriage and
caused a rack block
<remedy> 1. Open the front cover of the instrument
2. Press STOP
3. Push the sampling carriage assembly backwards
Etc.

33. Simple troubleshooting (example - recap)
Not DITA
DITA
<title> Blocked Rack
<condition> The rack is blocked on the
rotative tray. The instrument is
still working.
<cause> A sample moved out of its
place in the carriage and
caused a rack block
<remedy> 1. Open the front cover of the
instrument
2. Press STOP
3. Push the sampling carriage
assembly backwards
etc.

34. Troubleshooting : complex version
Complex problem => Multiple solutions
__________________________________
<title>
<shortdescription> Yes
<condition> skip: Info is in the <Title> and
<ShortDesc>
<troubleSolution> <cause> <title>
<remedy>
<step>
<step>

35. Complex problem (1)
http://www.techsoup.org/support/articles-and-how-
tos/do-it-yourself-desktop-troubleshooting

36. Complex troubleshooting (2)
(continued)
<title> Blank monitor
<shortdesc>
If the monitor is blank, although the computer is powered up, you may check the monitor power
plugging, the power button, the monitor's brightness controls, or the monitor's cables.
___________________________________________________________
<troubleSolution> <cause> <title>
Monitor power plugging
<cause> The monitor connections (wall socket or power strip) are faulty.
<remedy>
1. Check that the monitor is firmly plugged into a working wall socket or power strip
2. Check that the power strip is turned on
3. Check that the monitor's power button is switched to "ON"
4. If the problem is not corrected, try plugging the PC or power strip into another wall socket

37. Complex troubleshooting (3)
<title> Blank monitor
…
___________________________________________
<troubleSolution> <cause> <title>
Monitor brightness and contrast controls
<cause> The controls may be poorly adjusted.
<remedy>
<steps> 1. Press the A button at the bottom of monitor
2. On the Darkness window, adjust ...
3. etc.

38. <title> Blank monitor (4)
<title>
…
_____________________________________________
<troubleshooting> <cause> <title> Monitor cable
<cause> The monitor cable is not firmly plugged in or loosely screwed
<remedy>
1. Check the monitor cable is firmly plugged into the back of the d display
2. Check the pinned end is tightly screwed into the video output
3. Remove the existing cable and replace it with a know working one
Etc.

39. Multiple solutions (4) Recap
<title> Blank monitor
…
__________________________________________
<troubleSolution><cause> <title>
Monitor power plugging
<troubleSolution><cause> <title>
Monitor brightness and contrast controls
<troubleSolution><cause> <title>
Monitor cable
<troubleSolution><cause><title>
Monitor video card

40. Collecting Troubleshooting
topics
 Simple troubleshooting
 Complex troubleshooting
 in the troubleshooting chapter!

41. Embedded Troubleshooting
• Included in the task
• Small format: 1-step solution
• Add a visual signal :
• icon, sign, mention « Problem? »

42. Embedded troubleshooting –Example (1)
Configuring the AAA Application
1.To configure the AAA Application, select one of the system
configuration settings:
• Stand-alone system
• Networked system
2. In the BBB window, select the Z option
The system administration panel displays.

43. Embedded troubleshooting –Example (2)
Configuring the AAA application
<task> <steps><step>
etc.
<steptroubleshooting>
Trouble?
If an error message appears, the system configuration setting may be wrong.
• Click the Back button and select the other option

44. Troubleshooting Note-type
• @trouble same type as @caution, @note or @tip
• To be used as quick remedy
• Not to replace <steptroubleshooting> or
<tasktroubleshooting> in a task topic

45. Troubleshooting Note-type - Example
<concept>
<title>Performing Pediatric Defibrillation
<p> The CodeMaster XL+ paddle set comes with pediatric paddles. To use the pediatric paddle
set, depress the release latch at the front of the standard external paddle set while pulling
forward on the adult paddle surface. This action will remove the adult paddle contact surface and
expose the smaller pediatric contact surface. The clinician must select an appropriate energy level
for the pediatric patient. </p>
<note type="trouble">
Trouble? Energy level not defined? Turn the Energy Select control button to the desired energy
level.

46. Troubleshooting recap’
• Simple
• Complex
• Embedded
• Note-type

47. More questions?
flacke@orange.fr