Keep Calm and Design your Troubleshooting Topic
Until now, troubleshooting sections available in any type of documentation shows no consistency and resemble a troubleshooting salad. On the other hand, DITA expert Bob Thomas sets the Troubleshooting objective: “Allow writers to focus on addressing and solving specific problems users may encounter” (1) With DITA 1.3, authors might fear another (DITA) salad made of: tasktroubleshooting, steptroubleshooting, troubleshooting note-type, condition, remedy, cause, embedded troubleshooting,… How to keep calm and select the rules that best fit your users’ needs? This presentation aims at discussing when and where to use a plain troubleshooting topic, and when to select an embedded troubleshooting or a troubleshooting note-type.
___________
Bibliography:
(1) Bob Thomas, DITA 1.3 Troubleshooting topic -CMS/DITA North America 2015 conference
(2) “Error-information in tutorial documentation”, A. Lazonder, H. van der Meij in J.Human-Computer studies, 1995
What can attendees expect to learn?
The troubleshooting topic is an essential part of the DITA 1.3 version. As of now, designing a troubleshooting section has not been thoroughly analysed and defined; authors do need a sound troubleshooting model. The topic is an excellent framework for authors to get started. Its application may need some additional considerations as to selecting the types of troubleshooting option (plain troubleshooting topic, embedded or note-type) to fit their users’ need for error information.
Meet the Presenter
Marie-Louise Flacke is a graduate of the American University of Paris (Technical Writing Program).
Marie-Louise’s professional skills and interests range from DITA authoring to bid writing, readability indices and eye-tracking. She also provides technical writing courses at various French Universities, focusing on minimalism and usability testing.
Contracting with organizations like Deutsche Boerse and Vodafone, she intensified her practice in providing minimalist documentation and applying the minimalist rules to various types of documentation.