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

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 () or Skype

Time zone: Mountain (GMT-7)