Troubleshooting use cases

["Gershon Joseph (gerjosep)" <gerjosep@cisco.com>]

I've had an action for a while to knock up some use cases around troubleshooting. Here is a first draft, which I hope will stimulate some discussion to help refine and enhance the use cases. I've attached both DITA source and XHTML formats of the topic.

Regards,
Gershon

----------
Gershon L Joseph
TECHNICAL LEADER.ENGINEERING
Product Development Services, CDO
Chair, OASIS DITA Adoption Technical Committee
Member, OASIS DITA Technical Committee
Member, OASIS DocBook Technical Committee
E-Mail: gerjosep@cisco.com
Phone: +972 9 892 7157
Mobile: +972 57 314 1170


This email may contain confidential and privileged material for the sole use of the intended recipient. Any review, use, distribution or disclosure by others is strictly prohibited. If you are not the intended recipient (or authorized to receive for the recipient), please contact the sender by reply email and delete all copies of this message.

troubleshootingUseCases.dita

Title: Use cases for troubleshooting documentation

Use cases for troubleshooting documentation

Introduction

This article was developed as a result of the following DITA Technical Communication Subcommittee action item assigned to the author:

[13-Dec-2010, Troubleshooting docs] ACTION: Gershon Joseph took the action to document use cases to share with the group as possible basis for developing markup that could be included as specialization and/or recommended as addition.

USE CASE 1: Troubleshooting section within a task

There is often a need to include a troubleshooting section in a task, between the <result> and <postreq>. The purpose of this section is to help the reader resolve any problems that may arise should their result not match the result stated in the <result> section of the task. It is expected the reader would need this problem-solving information before reading the <postreq> section, since their is no sense in moving forward if the expected result was not achieved.

USE CASE 2: Troubleshooting statement within a step

There is often a need to include a troubleshooting statement in a task step, following the <stepresult>. The purpose of this "trouble" statement is to help the reader resolve any problems that may arise should their step result not match the result stated in the <stepresult> section of the step. Unlike use case 1, which applies to problem-solving upon completion of the entire set of steps, this use case helps the reader resolve a problem encountered while performing a specific step.

USE CASE 3: Troubleshooting topic

A troubleshooting topic describes how to troubleshoot a particular problem a user has encountered. This topic typically contains the following sections, in the order shown:

1. Problem statement
2. Possible cause (one or more)
3. Recommended solution (one or more)

A variation of this, which is arguably more user-friendly, is the following, which groups the cause and solution sections together:

1. Problem statement
2. Resolution path (one or more)

Each "resolution path" comprises one "possible cause" followed by one or more "recommended solutions".

USE CASE 4: Troubleshooting document

A troubleshooting document is used to aggregate troubleshooting topics into a deliverable. It may contain additional concept and/or reference topics, where relevant. When the deliverable is published to an online format, the related concepts and references may be links instead of being included as part of the deliverable.