Re: [dita-techcomm] Eberlein feedback about troubleshooting proposals

[Bob Thomas <bob.thomas@tagsmiths.com>]

Hi Kris,

Thank you for your review. It was quite helpful.

In this message, I am going to respond to your comments on 13086 and 13098. I expect that JoAnn will follow up separately

Proposal #13086

• Typo in the "Benefits" section:
• "This addition will benefit writers who want to provide important troubleshooting information within a step right that the point of need by the users"
• Probably should be something like "This addition will benefit writers who want to provide important troubleshooting information directly within a step right that the point of need by the users"
  Done
  

• Language Reference topic:
• Remove the mention of substep from the short description
  Done.
  
• Should mention that users should NOT use a <note type="trouble"/> within <steptroubleshooting>?
  Done. Placed a tip at the beginning of the refbody stating:
  Do not use <note type="troubleshooting"> inside of <steptroubleshooting> because its meaning there would be ambiguous.
  
• According to the minutes from 19 June 2012, <steptroubleshooting> was supposed to be specialized from topic/note with a fixed type of "trouble" -- NOT topic/itemgroup
  Declined. <steptroubleshooting> is a child of <step>. The <step> content model does not allow <note> as a child.
  
• Where should this topic be placed in the hierarchy? It obviously should be nested under 3.2.2 Task elements, but where?
  I believe that it should immediately follow the <stepresult> element.
  

Proposal #13096

• Language Reference topic:
• The <shortdesc> really needs more content; how about "The <tasktroubleshooting> element provides information that might assist users to resolve problems when they do not successfully complete a task. In particular, this element can be used to explain how users can recover when the results of a task do not match those listed in the <result> element."
  Done. The <shortdesc> now reads as follows:
  The <tasktroubleshooting> element provides users
  information for resolving problems that may occur when tasks do not complete as expected. In particular, this element can be used to explain how users can recover when the results of a task do not match those listed in the <result> element.
  
  
• Should mention that users should NOT use a <note type="trouble"/> within <tasktroubleshooting>?
  Done. Placed a tip at the beginning of the refbody stating:
  Do not use <note type="troubleshooting"> inside of <tasktroubleshooting> because its meaning there would be ambiguous.
  
• Where should this topic be placed in the hierarchy? It obviously should be nested under 3.2.2 Task elements, but where?
  I believe that it should immediately follow the <result> element.
  
• According to the minutes from 26 June 2012, this topic should mention that processors might need to generate an appropriate label for this element, to draw the users attention to the nature of the element's content.
  Needs further discussion. None of the other section specializations in taskbody make mention of labeling in their element descriptions even though there are processing expectations for them. Perhaps, these element descriptions should mention labeling. But, until they do, I would like to keep the labeling statement out of the <tasktroubleshooting> element description.
  

• We need suggested changes to "2.2.2.3 General task topic". (I think this only requires an additional row in the table in the "Comparison of general and strict task " section.)
• We need suggested changes to "2.2.2.4 Task topic (strict task)".

I addressed both of these comments by adding rows to the tables in the Modified specification documentation sections in proposals 13086 (steptroubleshooting) and 13096 (tasktroubleshooting).

Here are the changes for proposal 13086 (steptroubleshooting):

Location

Text in 1.2

Proposed chages for 1.3

2.2.2.4 Strict task topic/Structure section<steps>

The step element may also contain information <info>, substeps <substeps>, tutorial information <tutorialinfo>, a step example <stepxmp>, choices <choices>, or a stepresult <stepresult>, although these are optional.

The step element may also contain information <info>, substeps <substeps>, tutorial information <tutorialinfo>, a step example <stepxmp>, choices <choices>, a stepresult <stepresult>, or a <steptroubleshooting>, although these are optional.

Here are the changes for proposal 13096 (tasktroubleshooting):

Location

Text in 1.2

Proposed chages for 1.3

2.2.2.3 General task topic/Purpose section	Both task topics include sections for describing the context, prerequisites, expected results, and other aspects of a task.	Both task topics include sections for describing the context, prerequisites, expected results, troubleshooting, and other aspects of a task.
2.2.2.3 General task topic/Comparison table	[Both columns] result (optional, one only, precedes example)	[Both columns] result (optional, one only, precedes troubleshooting) troubleshooting (optional, one only, precedes example)
2.2.2.4 Strict task topic/Purpose section	Both task topics include sections for describing the context, prerequisites, expected results, and other aspects of a task.	Both task topics include sections for describing the context, prerequisites, expected results, troubleshooting, and other aspects of a task.
2.2.2.4 Strict task topic/Structure section/<tasktroubleshooting>	[N/A. New list item to follow <result>]	<tasktroubleshooting> Provides users information for resolving problems that occur when tasks do not complete as expected

Best Regards,

--
Bob Thomas

+1 720 201 8260

Skype: bob.thomas.colorado

Instant messaging: Gmail chat (bob.thomas@tagsmiths.com) or Skype

Time zone: Mountain (GMT-7)