OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

dita-techcomm message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]


Subject: 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: dita-techcomm@lists.oasis-open.org [mailto:dita-techcomm@lists.oasis-open.org] On Behalf Of Kristen James Eberlein
Sent: Saturday, March 30, 2013 5:30 PM
To: Buchholz, Thilo; Eliot Kimber; Doherty, Stan; dita-techcomm@lists.oasis-open.org
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



[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]