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

Thanks, Kris!

 

Let’s have a look at these during our SC call this morning.

 

 

-seth

 

From:  [mailto:]
On Behalf Of Kristen James Eberlein

Sent: Saturday, March 30, 2013 5:30 PM

To: Buchholz, Thilo; Eliot Kimber; Doherty, Stan; 

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

 

I wanted to do my review as quickly as possible, so please excuse me if my comments seem terse. Thanks for all the hard work in bring these proposals together!

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"

Language Reference topic:

Remove the mention of substep from the short description

Should mention that users should NOT use a <note type="trouble"/> within <steptroubleshooting>?

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

Where should this topic be placed in the hierarchy? It obviously should be nested under 3.2.2 Task elements, but where?

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."

Should mention that users should NOT use a <note type="trouble"/> within <tasktroubleshooting>?

Where should this topic be placed in the hierarchy? It obviously should be nested under 3.2.2 Task elements, but where?

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.

Proposal #13098

No comments

Architectural spec topics

"Troubleshooting information:

Third paragraph: Suggest removing "In the examples here, we use the word <i>Trouble?<i> as a possible symbol for troubleshooting. A symbol may be added through a stylesheet." Replace it with something like "Accordingly, we suggest that implementations use style
 sheets that add symbols or text to draw attention to the nature of the information in the troubleshooting elements."

Do we need the explicit content model information?

First example: Remove the phrase "Trouble?" from the beginning of the <steptroubleshooting> element. We don't want to suggest that it would be authored text.

Second example: Change "subjectScheme map" to "root map". (This is my error, as I suggested this example originally.)

Where should this topic be placed in the hierarchy? Obviously it should be part of 2.2 Architectural Specification: Technical Content Version, but where?

Third example: Remove the phrase "Trouble?" from the <tasktroubleshooting> element. Perhaps we need to show a screen capture of how processors might add text or a symbol to highlight the nature of the information?

Troubleshooting note section: This needs a statement warning users from using this note  in <steptroubleshooting> or <tasktroubleshooting>

General overall comment: I am concerned that this topic might not fully address the concerns that the TC brought up when discussing the three interrelated troubleshooting proposals at the 19 June 2012 meeting. To quote from the minutes: "There was also
 concern about whether authors might not understand where to use <note type="troubleshooting"> vs. where to use <steptroubleshooting>; there is, in fact, no syntactical way to keep an author from putting a troubleshooting note within a <steptroubleshooting>. 
 It was agreed that these troubleshooting proposals would require significant documentation in the spec. (and perhaps in a white paper?) in order to give guidance to authors."

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)".

-- 

Best,

Kris

Kristen James Eberlein

Principal consultant, Eberlein Consulting

Co-chair, OASIS DITA Technical Committee

Charter member, OASIS DITA Adoption Committee

www.eberleinconsulting.com

+1 919 682-2290; kriseberlein (skype