dita-techcomm — archive

[Gershon Joseph]

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: Problem statement Possible cause (one or more) 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: Problem statement 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.