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: Fwd: Kimber feedback about troubleshooting proposals




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/








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