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

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 <R01164@freescale.com> 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.

dita message