[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: 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:
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
Joann.hackos@comtech-serv.com
303-232-7586
From: Stan Doherty <stan@modularwriting.com>
Reply-To: Stan Doherty <stan@modularwriting.com> Date: Tuesday, March 5, 2013 3:01 AM To: DITA TC <dita@lists.oasis-open.org>, Park Seth-R01164 <R01164@freescale.com> Cc: "stan@modularwriting.com" <stan@modularwriting.com>, Kristen James Eberlein <kris@eberleinconsulting.com>, JoAnn Hackos <joann.hackos@comtech-serv.com>, "donrday@contelligencegroup.com" <donrday@contelligencegroup.com>, Park Seth-R01164 <R01164@freescale.com> 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 <R01164@freescale.com> wrote:
Stan Doherty
Director, Technical Publications Verivue Inc. |
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]