SlideShare uma empresa Scribd logo
1 de 47
Baixar para ler offline
DITA Troubleshooting topic
Keep calm
&
design your
troubleshooting topic
CMS DITA Europe conference
Munich, November 2015
Overview
• Authors & troubleshooting sections
• Experts recommendations
• DITA solution
Authors: play w/
« troubleshooting » messages
Authors: troubleshooting
variants
Authors: Troubleshooting
short form
https://medium.com/@thomasfuchs/how-to-write-an-error-message-883718173322
Authors: Troubleshooting
bla-bla
Authors: Troubleshooting
salad…
Authors: make it short
• Do these messages HELP the end-user
solve his problem ?
Authors: Puzzling
• Length
• long, short?
• Type
• Error messages?
• Descriptions?
• Questions?
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
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
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)
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 »)
How much information?
• « Our research suggests there should
be ample error information in the
manual »
More information?
minimalism?
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?
Troubleshooting history?
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…)
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)
Modeling
<troubleshooting>
<title>
<condition>
<cause>
<remedy>
Error detection
Pre-diagnosis
Diagnosis
Correction
Modeling (DITA 1.3)
<troubleshooting>
<title>
<shortdesc>
<prolog>
<troublebody> <condition>
<troubleSolution>
<cause>
<remedy>
DITA 1.3:
the troubleshooting types
1. Simple troubleshooting information
2. Complex troubleshooting information
3. Embedded troubleshooting
4. Troubleshooting note
Simple Troubleshooting
• Title
• Condition (situation when the error occurs)
• Cause (of the symptom)
• Remedy (to restore the system)
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
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?
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”
<title>
• Title should match the most likely way
a user would describe the problem
• User’s terminology
• Add <indexterms> to provide search
options
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
Short description
• Useful in case of complex
troubleshooting information:
• Multiple solutions
• ShortDesc informs about the various
solutions
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.
Simple troubleshooting
(example)
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.
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.
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>
Complex problem (1)
http://www.techsoup.org/support/articles-and-how-
tos/do-it-yourself-desktop-troubleshooting
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
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.
<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.
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
Collecting Troubleshooting
topics
 Simple troubleshooting
 Complex troubleshooting
 in the troubleshooting chapter!
Embedded Troubleshooting
• Included in the task
• Small format: 1-step solution
• Add a visual signal :
• icon, sign, mention « Problem? »
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.
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
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
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.
Troubleshooting recap’
• Simple
• Complex
• Embedded
• Note-type
More questions?
flacke@orange.fr

Mais conteúdo relacionado

Semelhante a DITA Troubleshooting topic

Common PC Problems and How to Troubleshoot Them for Immigration.pptx
Common PC Problems and How to Troubleshoot Them for Immigration.pptxCommon PC Problems and How to Troubleshoot Them for Immigration.pptx
Common PC Problems and How to Troubleshoot Them for Immigration.pptxkhalidgabbal
 
Help your tech
Help your tech Help your tech
Help your tech stantons
 
Handling Vendor Problems, or Problems With Vendors
Handling Vendor Problems,  or Problems With VendorsHandling Vendor Problems,  or Problems With Vendors
Handling Vendor Problems, or Problems With VendorsSam Knutson
 
Troubleshooting Your PC (From MedRule Business Solutions)
Troubleshooting Your PC (From MedRule Business Solutions)Troubleshooting Your PC (From MedRule Business Solutions)
Troubleshooting Your PC (From MedRule Business Solutions)csswebgirl
 
Paul Giralt Without Ch# 6
Paul Giralt Without Ch# 6Paul Giralt Without Ch# 6
Paul Giralt Without Ch# 6guest6cfa525
 
CIS 246 Massive Success--snaptutorial.com
CIS 246  Massive Success--snaptutorial.comCIS 246  Massive Success--snaptutorial.com
CIS 246 Massive Success--snaptutorial.comsantricksapiens62
 
CIS 246 Technology levels--snaptutorial.com
CIS 246 Technology levels--snaptutorial.comCIS 246 Technology levels--snaptutorial.com
CIS 246 Technology levels--snaptutorial.comsholingarjosh55
 
Cis 246 Success Begins / snaptutorial.com
Cis 246 Success Begins / snaptutorial.comCis 246 Success Begins / snaptutorial.com
Cis 246 Success Begins / snaptutorial.comRobinson067
 
Cis 246 Enthusiastic Study / snaptutorial.com
Cis 246 Enthusiastic Study / snaptutorial.comCis 246 Enthusiastic Study / snaptutorial.com
Cis 246 Enthusiastic Study / snaptutorial.comGeorgeDixon96
 
We Make Debugging Sucks Less
We Make Debugging Sucks LessWe Make Debugging Sucks Less
We Make Debugging Sucks LessAlon Fliess
 
Could not-reconnect-all-network-drives
Could not-reconnect-all-network-drivesCould not-reconnect-all-network-drives
Could not-reconnect-all-network-drivesssuser1eca7d
 
Guide to Helping your Tech Help You
Guide to Helping your Tech Help YouGuide to Helping your Tech Help You
Guide to Helping your Tech Help YouDesiree Caskey
 
Case Study of the Unexplained
Case Study of the UnexplainedCase Study of the Unexplained
Case Study of the Unexplainedshannomc
 

Semelhante a DITA Troubleshooting topic (20)

Basic Troubleshooting
Basic TroubleshootingBasic Troubleshooting
Basic Troubleshooting
 
Common PC Problems and How to Troubleshoot Them for Immigration.pptx
Common PC Problems and How to Troubleshoot Them for Immigration.pptxCommon PC Problems and How to Troubleshoot Them for Immigration.pptx
Common PC Problems and How to Troubleshoot Them for Immigration.pptx
 
CC-112-Lec.1.ppsx
CC-112-Lec.1.ppsxCC-112-Lec.1.ppsx
CC-112-Lec.1.ppsx
 
Lesson 3.2
Lesson 3.2Lesson 3.2
Lesson 3.2
 
Help your tech
Help your tech Help your tech
Help your tech
 
Handling Vendor Problems, or Problems With Vendors
Handling Vendor Problems,  or Problems With VendorsHandling Vendor Problems,  or Problems With Vendors
Handling Vendor Problems, or Problems With Vendors
 
Troubleshooting Your PC (From MedRule Business Solutions)
Troubleshooting Your PC (From MedRule Business Solutions)Troubleshooting Your PC (From MedRule Business Solutions)
Troubleshooting Your PC (From MedRule Business Solutions)
 
Paul Giralt Without Ch# 6
Paul Giralt Without Ch# 6Paul Giralt Without Ch# 6
Paul Giralt Without Ch# 6
 
CIS 246 Massive Success--snaptutorial.com
CIS 246  Massive Success--snaptutorial.comCIS 246  Massive Success--snaptutorial.com
CIS 246 Massive Success--snaptutorial.com
 
CIS 246 Technology levels--snaptutorial.com
CIS 246 Technology levels--snaptutorial.comCIS 246 Technology levels--snaptutorial.com
CIS 246 Technology levels--snaptutorial.com
 
Cis 246 Success Begins / snaptutorial.com
Cis 246 Success Begins / snaptutorial.comCis 246 Success Begins / snaptutorial.com
Cis 246 Success Begins / snaptutorial.com
 
Cis 246 Enthusiastic Study / snaptutorial.com
Cis 246 Enthusiastic Study / snaptutorial.comCis 246 Enthusiastic Study / snaptutorial.com
Cis 246 Enthusiastic Study / snaptutorial.com
 
Algorithm.pdf
Algorithm.pdfAlgorithm.pdf
Algorithm.pdf
 
We Make Debugging Sucks Less
We Make Debugging Sucks LessWe Make Debugging Sucks Less
We Make Debugging Sucks Less
 
midterm_fa07.pdf
midterm_fa07.pdfmidterm_fa07.pdf
midterm_fa07.pdf
 
Birth 1
Birth 1Birth 1
Birth 1
 
Could not-reconnect-all-network-drives
Could not-reconnect-all-network-drivesCould not-reconnect-all-network-drives
Could not-reconnect-all-network-drives
 
Guide to Helping your Tech Help You
Guide to Helping your Tech Help YouGuide to Helping your Tech Help You
Guide to Helping your Tech Help You
 
Case Study of the Unexplained
Case Study of the UnexplainedCase Study of the Unexplained
Case Study of the Unexplained
 
Imd 203 Questions
Imd 203 QuestionsImd 203 Questions
Imd 203 Questions
 

Último

F.LAB Credential ©2024 : Looking The World of Experience by F.LAB
F.LAB Credential ©2024 : Looking The World of Experience by F.LABF.LAB Credential ©2024 : Looking The World of Experience by F.LAB
F.LAB Credential ©2024 : Looking The World of Experience by F.LAButariworks
 
Mike Tyson Sign The Contract Big Boy Shirt
Mike Tyson Sign The Contract Big Boy ShirtMike Tyson Sign The Contract Big Boy Shirt
Mike Tyson Sign The Contract Big Boy ShirtTeeFusion
 
Sign The Contract Big Boy Shirt Sign The Contract Big Boy Shirt
Sign The Contract Big Boy Shirt  Sign The Contract Big Boy ShirtSign The Contract Big Boy Shirt  Sign The Contract Big Boy Shirt
Sign The Contract Big Boy Shirt Sign The Contract Big Boy ShirtTeeFusion
 
Cayden Ingman's apparel design portfolio | Oregon State University|
Cayden Ingman's apparel design portfolio | Oregon State University|Cayden Ingman's apparel design portfolio | Oregon State University|
Cayden Ingman's apparel design portfolio | Oregon State University|CaydenIngman
 
Jackson Henry 24 Flock The Vote Shirt Jackson Henry 24 Flock The Vote Shirt
Jackson Henry 24 Flock The Vote Shirt  Jackson Henry 24 Flock The Vote ShirtJackson Henry 24 Flock The Vote Shirt  Jackson Henry 24 Flock The Vote Shirt
Jackson Henry 24 Flock The Vote Shirt Jackson Henry 24 Flock The Vote ShirtTeeFusion
 
FARMER'S HOUSING PORTFOLIO. DESIGN PTOBLEM OF 7TH SEM. ARCHITECTURE DESIGN.
FARMER'S HOUSING PORTFOLIO. DESIGN PTOBLEM OF 7TH SEM. ARCHITECTURE DESIGN.FARMER'S HOUSING PORTFOLIO. DESIGN PTOBLEM OF 7TH SEM. ARCHITECTURE DESIGN.
FARMER'S HOUSING PORTFOLIO. DESIGN PTOBLEM OF 7TH SEM. ARCHITECTURE DESIGN.Vaishnavi R
 
SHADES Explained (Branding & Packaging) .pdf
SHADES Explained (Branding & Packaging) .pdfSHADES Explained (Branding & Packaging) .pdf
SHADES Explained (Branding & Packaging) .pdfaimonayesha7
 
ALISIA: HOW MIGHT WE ACHIEVE HIGH ENVIRONMENTAL PERFORMANCE WHILE MAINTAINING...
ALISIA: HOW MIGHT WE ACHIEVE HIGH ENVIRONMENTAL PERFORMANCE WHILE MAINTAINING...ALISIA: HOW MIGHT WE ACHIEVE HIGH ENVIRONMENTAL PERFORMANCE WHILE MAINTAINING...
ALISIA: HOW MIGHT WE ACHIEVE HIGH ENVIRONMENTAL PERFORMANCE WHILE MAINTAINING...Peter139483
 
Unit 12 - Level Design and how it affects the player.
Unit 12 - Level Design and how it affects the player.Unit 12 - Level Design and how it affects the player.
Unit 12 - Level Design and how it affects the player.JoshHolmes21
 
Oregon State University Interior Design Portfolio
Oregon State University Interior Design PortfolioOregon State University Interior Design Portfolio
Oregon State University Interior Design Portfoliopagei
 
second stories test a method kit for co creationnnnnnn
second stories test a method kit for co creationnnnnnnsecond stories test a method kit for co creationnnnnnn
second stories test a method kit for co creationnnnnnnjohannesrothkegel
 
Digi Pack for the impulse band coursework.pptx
Digi Pack for the impulse band coursework.pptxDigi Pack for the impulse band coursework.pptx
Digi Pack for the impulse band coursework.pptxRufusGleave
 
如何办理西英格兰大学毕业证书学位证书成绩单?
如何办理西英格兰大学毕业证书学位证书成绩单?如何办理西英格兰大学毕业证书学位证书成绩单?
如何办理西英格兰大学毕业证书学位证书成绩单?krc0yvm5
 
Revit Drafting – Drafting Tools and Software
Revit Drafting – Drafting Tools and SoftwareRevit Drafting – Drafting Tools and Software
Revit Drafting – Drafting Tools and SoftwareResDraft
 
DSGN 253 Design Portfolio Project - Julien Fedou
DSGN 253 Design Portfolio Project - Julien FedouDSGN 253 Design Portfolio Project - Julien Fedou
DSGN 253 Design Portfolio Project - Julien Fedoujfedou2105
 
DesignKit IDEO Human-Centered Design course report
DesignKit IDEO Human-Centered Design course reportDesignKit IDEO Human-Centered Design course report
DesignKit IDEO Human-Centered Design course reportstudiotelon
 
Complete Coffee table book on Jiapur.pdf
Complete Coffee table book on Jiapur.pdfComplete Coffee table book on Jiapur.pdf
Complete Coffee table book on Jiapur.pdfaimonayesha7
 
ورشة الطريق إلى البيم ورشة الطريق إلى البيم
ورشة الطريق إلى البيم   ورشة الطريق إلى البيمورشة الطريق إلى البيم   ورشة الطريق إلى البيم
ورشة الطريق إلى البيم ورشة الطريق إلى البيمOmarSelim27
 
MIRAE (Branding & Identity) Explained.pdf
MIRAE (Branding & Identity) Explained.pdfMIRAE (Branding & Identity) Explained.pdf
MIRAE (Branding & Identity) Explained.pdfaimonayesha7
 
Strawberry Jams But My Glock Don't Shirt
Strawberry Jams But My Glock Don't ShirtStrawberry Jams But My Glock Don't Shirt
Strawberry Jams But My Glock Don't ShirtTeeFusion
 

Último (20)

F.LAB Credential ©2024 : Looking The World of Experience by F.LAB
F.LAB Credential ©2024 : Looking The World of Experience by F.LABF.LAB Credential ©2024 : Looking The World of Experience by F.LAB
F.LAB Credential ©2024 : Looking The World of Experience by F.LAB
 
Mike Tyson Sign The Contract Big Boy Shirt
Mike Tyson Sign The Contract Big Boy ShirtMike Tyson Sign The Contract Big Boy Shirt
Mike Tyson Sign The Contract Big Boy Shirt
 
Sign The Contract Big Boy Shirt Sign The Contract Big Boy Shirt
Sign The Contract Big Boy Shirt  Sign The Contract Big Boy ShirtSign The Contract Big Boy Shirt  Sign The Contract Big Boy Shirt
Sign The Contract Big Boy Shirt Sign The Contract Big Boy Shirt
 
Cayden Ingman's apparel design portfolio | Oregon State University|
Cayden Ingman's apparel design portfolio | Oregon State University|Cayden Ingman's apparel design portfolio | Oregon State University|
Cayden Ingman's apparel design portfolio | Oregon State University|
 
Jackson Henry 24 Flock The Vote Shirt Jackson Henry 24 Flock The Vote Shirt
Jackson Henry 24 Flock The Vote Shirt  Jackson Henry 24 Flock The Vote ShirtJackson Henry 24 Flock The Vote Shirt  Jackson Henry 24 Flock The Vote Shirt
Jackson Henry 24 Flock The Vote Shirt Jackson Henry 24 Flock The Vote Shirt
 
FARMER'S HOUSING PORTFOLIO. DESIGN PTOBLEM OF 7TH SEM. ARCHITECTURE DESIGN.
FARMER'S HOUSING PORTFOLIO. DESIGN PTOBLEM OF 7TH SEM. ARCHITECTURE DESIGN.FARMER'S HOUSING PORTFOLIO. DESIGN PTOBLEM OF 7TH SEM. ARCHITECTURE DESIGN.
FARMER'S HOUSING PORTFOLIO. DESIGN PTOBLEM OF 7TH SEM. ARCHITECTURE DESIGN.
 
SHADES Explained (Branding & Packaging) .pdf
SHADES Explained (Branding & Packaging) .pdfSHADES Explained (Branding & Packaging) .pdf
SHADES Explained (Branding & Packaging) .pdf
 
ALISIA: HOW MIGHT WE ACHIEVE HIGH ENVIRONMENTAL PERFORMANCE WHILE MAINTAINING...
ALISIA: HOW MIGHT WE ACHIEVE HIGH ENVIRONMENTAL PERFORMANCE WHILE MAINTAINING...ALISIA: HOW MIGHT WE ACHIEVE HIGH ENVIRONMENTAL PERFORMANCE WHILE MAINTAINING...
ALISIA: HOW MIGHT WE ACHIEVE HIGH ENVIRONMENTAL PERFORMANCE WHILE MAINTAINING...
 
Unit 12 - Level Design and how it affects the player.
Unit 12 - Level Design and how it affects the player.Unit 12 - Level Design and how it affects the player.
Unit 12 - Level Design and how it affects the player.
 
Oregon State University Interior Design Portfolio
Oregon State University Interior Design PortfolioOregon State University Interior Design Portfolio
Oregon State University Interior Design Portfolio
 
second stories test a method kit for co creationnnnnnn
second stories test a method kit for co creationnnnnnnsecond stories test a method kit for co creationnnnnnn
second stories test a method kit for co creationnnnnnn
 
Digi Pack for the impulse band coursework.pptx
Digi Pack for the impulse band coursework.pptxDigi Pack for the impulse band coursework.pptx
Digi Pack for the impulse band coursework.pptx
 
如何办理西英格兰大学毕业证书学位证书成绩单?
如何办理西英格兰大学毕业证书学位证书成绩单?如何办理西英格兰大学毕业证书学位证书成绩单?
如何办理西英格兰大学毕业证书学位证书成绩单?
 
Revit Drafting – Drafting Tools and Software
Revit Drafting – Drafting Tools and SoftwareRevit Drafting – Drafting Tools and Software
Revit Drafting – Drafting Tools and Software
 
DSGN 253 Design Portfolio Project - Julien Fedou
DSGN 253 Design Portfolio Project - Julien FedouDSGN 253 Design Portfolio Project - Julien Fedou
DSGN 253 Design Portfolio Project - Julien Fedou
 
DesignKit IDEO Human-Centered Design course report
DesignKit IDEO Human-Centered Design course reportDesignKit IDEO Human-Centered Design course report
DesignKit IDEO Human-Centered Design course report
 
Complete Coffee table book on Jiapur.pdf
Complete Coffee table book on Jiapur.pdfComplete Coffee table book on Jiapur.pdf
Complete Coffee table book on Jiapur.pdf
 
ورشة الطريق إلى البيم ورشة الطريق إلى البيم
ورشة الطريق إلى البيم   ورشة الطريق إلى البيمورشة الطريق إلى البيم   ورشة الطريق إلى البيم
ورشة الطريق إلى البيم ورشة الطريق إلى البيم
 
MIRAE (Branding & Identity) Explained.pdf
MIRAE (Branding & Identity) Explained.pdfMIRAE (Branding & Identity) Explained.pdf
MIRAE (Branding & Identity) Explained.pdf
 
Strawberry Jams But My Glock Don't Shirt
Strawberry Jams But My Glock Don't ShirtStrawberry Jams But My Glock Don't Shirt
Strawberry Jams But My Glock Don't Shirt
 

DITA Troubleshooting topic

  • 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
  • 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?
  • 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)
  • 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.
  • 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>
  • 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