Re: Reviewer (Doherty) Feedback on DITA 1.3 Proposals #13086, #13096, and #13098

Hi Stan,

Thank you for your thorough review and comments.

One question: 

Technical requirements / Processing impact

  > Comment: I am not sure what to make of the statement "None.

    Processing should fall back to that defined for topic/note."

    Would there be a "troubleshooting" icon or label preceding

    this element when processed? If so, why not simply add 

    <note type="trouble"/> in this location?

Since we cannot mandate a new icon, I believe this is the only position we can take with regard to processing. In the topic I'm writing about the three troubleshooting options, I do recommend the use of a Trouble icon.

JoAnn

JoAnn T. Hackos, PhD

President

Comtech Services Inc.

710 Kipling Street, Suite 400

Denver, CO 80215



303-232-7586

From: Stan Doherty <>

Reply-To: Stan Doherty <>

Date: Tuesday, March 5, 2013 3:01 AM

To: DITA TC <>, Park Seth-R01164 <>

Cc: "" <>, Kristen James Eberlein <>,
 JoAnn Hackos <>, "" <>,
 Park Seth-R01164 <>

Subject: Reviewer (Doherty) Feedback on DITA 1.3 Proposals #13086, #13096, and #13098

Hi all -- 

  

Nice work! I like these proposed features very much. The following comments represent friendly technical and editorial feedback relative to the 

https://www.oasis-open.org/apps/org/workgroup/dita-techcomm/download.php/48126/stage3_04feb13.zip content.

  

Stan Doherty 

DITA TC 

Verivue/Akamai 

  

TOPIC: Stage 3 proposal: Feature 13086

================================================================

- Short description:

  > Line edit:

    FROM: "Proposal to add a new element to support a

          troubleshooting statement after the <stepresult> element

          in a task topic."

    TO:   "Proposal to add a new element to support a

          troubleshooting statement after the <stepresult> element

          
in a <step> element in a task topic." 

- Clarification: Perhaps note somewhere that <steptroubleshooting> cannot

  be inserted within other "step" sub-elements such as <substeps>

  or <stepsxmp>.

- Clarification: Perhaps note somewhere that <steptroubleshooting>

  currently ends a <step> element. I do not believe that a writer

  can insert another element AFTER <steptroubleshooting> within

  the <step>.

- Approved technical requirements

  > Line edit:

    FROM: "Add troubleshooting element to a step: There is often

          a need to include a troubleshooting statement in a

          task step, following the <stepresult>.  . . ."

    TO:   "Add troubleshooting element to a step: There is often

          a need to include a troubleshooting statement in a

          task step, following the <stepresult>
element.  . . ." 

- Use cases

  > Line edit:

    FROM: "There is often a need to include a troubleshooting

          statement in a task step, following the <stepresult>."

    TO:   "There is often a need to include a troubleshooting

          statement in a task step, following the <stepresult>

          
element." 

- Modified DTDs

  > Line edit:

    FROM: "The only DTD file affected is dtd.mod under

          techincialContent/dtd."

    TO:   "The only DTD file affected is dtd.mod under

          
technicalContent/dtd." 

- Technical requirements / Processing impact

  > Comment: I am not sure what to make of the statement "None.

    Processing should fall back to that defined for topic/note."

    Would there be a "troubleshooting" icon or label preceding

    this element when processed? If so, why not simply add

    <note type="trouble"/> in this location?

TOPIC: Stage 3 proposal: Feature 13096

================================================================

- Short description:

  > Line edit:

    FROM: "Proposal to add a new element to support a troubleshooting

          section between the <result> and <example> elements

          in a task topic"

    TO:   "Proposal to add a new element to support a troubleshooting

          section between the <result> element and
either the 

          <example> or the <postreq> element in a task topic"

- Approved technical requirements

  > Line edit:

    FROM: "Add troubleshooting section with a task: There is often

          a need to include a troubleshooting section in a task,

          between the <result> and <postreq>."

    TO:   "Add a troubleshooting section within a task: There is often

          a need to include a troubleshooting section in a task,

          specifically between the <result>
element and either the 

          <example> or the <postreq> element in a task topic."

  > Line edit:

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

    TO:   "It is expected the reader would need this problem-solving

          information before reading the <postreq> section, since

          
there would be no sense in moving forward if the expected result

          
were not achieved." 

- Use cases

  > Line edit:

    FROM: "It is expected the reader would need this problem-solving

          information after reading the <result> section, since their

          is no sense in moving forward if the expected result was

          not achieved."

    TO:   "It is expected that the reader would need this problem-solving

          information after reading the <result> section, since
there 

          
would be no sense in moving forward if the expected result 
were 

          not achieved."

- Modified DTDs

  > Line edit:

    FROM: "A new element named <tasktroubleshooting> will follow <result>

          and precede <example> as an optional element. The only DTD

          file affected is dtd.mod under techincialContent/dtd."

    TO:   "A new element named <tasktroubleshooting> will follow the

          <result>
element and precede 
either the <example> or the 

          <stepreq> element as an optional element. The only DTD

          file affected is dtd.mod under
technicalContent/dtd." 

TOPIC: tasktroubleshooting

===========================================================================

- Example:

  > Additional example information/context

    
<steps> . . . </steps> 

    <result>The <uicontrol>User Type</uicontrol> menu updates to display

      the new types you added.</result>

    <tasktroubleshooting>If the User Type menu does not display

      the additions, manually refresh the page.</tasktroubleshooting>

    
<example>For example, you could also do xyz.</example> 

    <postreq>Once completed, you need to consider abc.</postreq>

TOPIC: Stage 3 proposal: Feature 13098

============================================================================

- Editorial: Not a bad idea to start implementing the convention for

  specifiying <element-names> and @attribute-names .

- This is the enhancement that I could use throughout my existing topics.

  

  

  

  

  

On March 4, 2013 at 12:28 PM Park Seth-R01164 <> wrote:

Dear TC,

 

Today the TechComm SC gave final approval for three proposal to reviewed by the TC (pursuant to Stage three requirements):

·        
13096

·        
13086

·        
13098

 

All materials are available in a single zip archive: 
https://www.oasis-open.org/apps/org/workgroup/dita-techcomm/download.php/48126/stage3_04feb13.zip. The Trello cards have been updated.

 

We have received 4 TC volunteers to review the proposals: Eliot Kimber, Stan Doherty, Kris Eberlein, and Thilo Bucholtz

 

I would like to recognize the outstanding commitment of Bob Thomas throughout the process of articulating these proposals and the supporting materials. Thanks also to the entire SC for their reviews and constructive criticism.

 

Thanks in advance to our TC reviewers!

 

 

-seth park

  

Stan Doherty 

Director, Technical Publications 

Verivue Inc.