Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

DITA Troubleshooting topic

9 views

Published on

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)

Published in: Design
  • DOWNLOAD FULL BOOKS, INTO AVAILABLE FORMAT ......................................................................................................................... ......................................................................................................................... 1.DOWNLOAD FULL. PDF EBOOK here { https://tinyurl.com/y6a5rkg5 } ......................................................................................................................... 1.DOWNLOAD FULL. EPUB Ebook here { https://tinyurl.com/y6a5rkg5 } ......................................................................................................................... 1.DOWNLOAD FULL. doc Ebook here { https://tinyurl.com/y6a5rkg5 } ......................................................................................................................... 1.DOWNLOAD FULL. PDF EBOOK here { https://tinyurl.com/y6a5rkg5 } ......................................................................................................................... 1.DOWNLOAD FULL. EPUB Ebook here { https://tinyurl.com/y6a5rkg5 } ......................................................................................................................... 1.DOWNLOAD FULL. doc Ebook here { https://tinyurl.com/y6a5rkg5 } ......................................................................................................................... ......................................................................................................................... ......................................................................................................................... .............. Browse by Genre Available eBooks ......................................................................................................................... Art, Biography, Business, Chick Lit, Children's, Christian, Classics, Comics, Contemporary, Cookbooks, Crime, Ebooks, Fantasy, Fiction, Graphic Novels, Historical Fiction, History, Horror, Humor And Comedy, Manga, Memoir, Music, Mystery, Non Fiction, Paranormal, Philosophy, Poetry, Psychology, Religion, Romance, Science, Science Fiction, Self Help, Suspense, Spirituality, Sports, Thriller, Travel, Young Adult,
       Reply 
    Are you sure you want to  Yes  No
    Your message goes here
  • Be the first to like this

DITA Troubleshooting topic

  1. 1. Keep calm & design your troubleshooting topic CMS DITA Europe conference Munich, November 2015
  2. 2. Overview • Authors & troubleshooting sections • Experts recommendations • DITA solution
  3. 3. Authors: play w/ « troubleshooting » messages
  4. 4. Authors: troubleshooting variants
  5. 5. Authors: Troubleshooting short form https://medium.com/@thomasfuchs/how-to-write-an-error-message-883718173322
  6. 6. Authors: Troubleshooting bla-bla
  7. 7. Authors: Troubleshooting salad…
  8. 8. Authors: make it short • Do these messages HELP the end-user solve his problem ?
  9. 9. Authors: Puzzling • Length • long, short? • Type • Error messages? • Descriptions? • Questions?
  10. 10. 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
  11. 11. 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
  12. 12. 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)
  13. 13. 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 »)
  14. 14. How much information? • « Our research suggests there should be ample error information in the manual » More information? minimalism?
  15. 15. 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?
  16. 16. Troubleshooting history?
  17. 17. 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…)
  18. 18. 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)
  19. 19. Modeling <troubleshooting> <title> <condition> <cause> <remedy> Error detection Pre-diagnosis Diagnosis Correction
  20. 20. Modeling (DITA 1.3) <troubleshooting> <title> <shortdesc> <prolog> <troublebody> <condition> <troubleSolution> <cause> <remedy>
  21. 21. DITA 1.3: the troubleshooting types 1. Simple troubleshooting information 2. Complex troubleshooting information 3. Embedded troubleshooting 4. Troubleshooting note
  22. 22. Simple Troubleshooting • Title • Condition (situation when the error occurs) • Cause (of the symptom) • Remedy (to restore the system)
  23. 23. 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
  24. 24. 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?
  25. 25. 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”
  26. 26. <title> • Title should match the most likely way a user would describe the problem • User’s terminology • Add <indexterms> to provide search options
  27. 27. 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
  28. 28. Short description • Useful in case of complex troubleshooting information: • Multiple solutions • ShortDesc informs about the various solutions
  29. 29. 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.
  30. 30. Simple troubleshooting (example)
  31. 31. 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.
  32. 32. 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.
  33. 33. 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>
  34. 34. Complex problem (1) http://www.techsoup.org/support/articles-and-how- tos/do-it-yourself-desktop-troubleshooting
  35. 35. 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
  36. 36. 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.
  37. 37. <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.
  38. 38. 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
  39. 39. Collecting Troubleshooting topics  Simple troubleshooting  Complex troubleshooting  in the troubleshooting chapter!
  40. 40. Embedded Troubleshooting • Included in the task • Small format: 1-step solution • Add a visual signal : • icon, sign, mention « Problem? »
  41. 41. 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.
  42. 42. 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
  43. 43. 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
  44. 44. 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.
  45. 45. Troubleshooting recap’ • Simple • Complex • Embedded • Note-type
  46. 46. More questions? flacke@orange.fr

×