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) -------- Original Message -------- Subject: Kimber feedback about troubleshooting proposals Date: Sun, 31 Mar 2013 11:39:54 -0500 From: Eliot Kimber <
ekimber@rsicms.com> To: Buchholz, Thilo <
thilo.buchholz@sap.com> , Doherty, Stan <
sdoherty@verivue.com> ,
dita-techcomm@lists.oasis-open.org <
dita-techcomm@lists.oasis-open.org> , Kristen James Eberlein <
kris@eberleinconsulting.com> I agree with all of Kris' comments. My specific comments: TroubleshootingElements.dita: 1. change: Troubleshooting information may also be added in any topic type as an attribute on the <note> element. To: Troubleshooting information may also be added in any topic type using a <note> element with a type of trouble . It is the note that provides the information, not the attribute. 2. Examples should be reformatted to limit the line length to about 40 characters max, otherwise they will not render well in many environments. Also, reduce the indention to 2 characters per level to minimize horizontal space requirements. 3. In the examples, suggest highlighting with bold the specific markup Items the example demonstrates (e.g., the <steptroubleshooting> element. 4. Change deals with to addresses or highlights (or similar) in this sentence: At times it is useful to add a <note> element that deals with a potential problem To: At times it is useful to add a <note> element that addresses a potential problem ----------------------------------------------- Proposal 13806, <steptroubleshooting> element: 1. Under modified DTDs the proposal says dtd.mod is the affected file, but it is actually task.mod . 2. The proposal says that <steptroubleshooting> will not be available in <substep> but in fact it is in the task.mod provided in the revised task.mod topic. I can think of no reason *not* to allow <steptroubleshooting> in <substep>--I would find it very surprising if it were not allowed there. So the proposal should be updated to reflect <steptroubleshooting> allowed in <substep>. 3. In the steptroubleshooting topic, the example is: --- <steptroubleshooting>If an error message displays during the system backup, locate the error ID in the <cite>Troubleshooting Guide</cite> and follow the instructions there.</steptroubleshooting> --- While <itemgroup> allows mixed content, I would expect best practice to be to use <p> within <steptroubleshooting>. In the case where you had multiple possible trouble conditions for a single step, you'd have to use <p> or some other markup (dl, ul, etc.), so probably good practice to always have a block wrapper around the contents of <steptroubleshooting>. I would suggest at a minimum showing two examples, the current simplest-possible one and one with two or more statements that uses nested <p> elements. 4. Along those same lines, the intent of the write up seems to be that <steptroubleshooting> is a single statement, but it seems equally likely that it might be multiple statements or even a complete troubleshooting tree, depending on the nature of the step. The description of the <steptroubleshooting> element should make that possibility explicitly allowed. If the intent of <steptroubleshooting> is that it be a single statement, then the content of <steptroubleshooting> should be limited to phrase-level content, not full itemgroup content. Likewise, if it is intended to be a single statement, then it should be repeatable. But I don't think tbat it is actually the intent of the proposal for <steptroubleshooting> to be a single statement in all cases. ----------------------------------------------- Proposal 13096, <tasktroubleshooting> element: 1. The shortdesc needs to be expanded on to say more about what the intended content of a <tasktroubleshooting> element would typically contain. In general all the Lang Ref topics are too brief and reflect a presumed shared understanding of usage semantics that does not hold in practice, so we should endeavor to correct that in our new topics. 2. As for <steptroubleshooting>, add an example of multiple statements showing appropriate markup (e.g., <p>, a list, whatever). ----------------------------------------------- Proposal 13098, trouble value for @type on <note>: 1. In addition to the reference entry for <note>, must also update the topic on type to add the new trouble value and a description of what it means. Cheers, Eliot -- Eliot Kimber Senior Solutions Architect, RSI Content Solutions Bringing Strategy, Content, and Technology Together Main: 512.554.9368
www.rsicms.com www.rsuitecms.com Book: DITA For Practitioners, from XML Press,
http://xmlpress.net/publications/dita/practitioners-1/