Next in thread →
Next in month →
Re: [dita] Comments from Dan Dionne about the troubleshooting topic proposal (13097)
Hi,
Dan and I have been corresponding directly about this. His message to Michael and Robert is essentially the same one that he sent to me.
To address Dan's comments about basic elements, I forwarded his concerns to Eliot Kimber since Eliot was the chief proponent for requiring troubleSolution when multiple remedy elements are required. Eliot agreed that we should to revert to the former model if that will solve Dan's issue with basic elements. I would like to do so.
As for Dan's remarks about remedy, I have the following observations:
The presence of steps and steps-unordered can be removed from remedy by constraints, or through omission, when it is time for the IBM troubleshooting specialization to be refactored.
The responsibleParty element was the result of a collaborative effort that I had with Dan last Summer. At that time we decided to specialize from topic/data. I am no longer comfortable with that decision. I believe that the specialization should come from topic/p instead so that it will be structurally compatible with the ts*Resolve elements in the IBM troubleshooting specialization.
The remarks about topic/title are a concern I have about any DITA section-like that will be used for authoring. I simply perpetuated the design pattern already present in topic/section because I felt that this proposal was not the right place to address my concern about the availability of topic/title.
Dan's remarks about element containment are asking for something that simply isn't available in remedy because it isn't available in topic/section. Perhaps changing responsibleParty from topic/data to topic/p will solve this problem. If nothing else it will be no more problematic than it is in the IBM Troubleshooting specialization.
I have already sent these remarks to Dan. Unfortunately for us, Dan will be on out of the office for two weeks, so I am not expecting to hear back from him soon.
Best Regards,
Bob Thomas
On Tue, Aug 6, 2013 at 6:06 AM, Kristen James Eberlein <> wrote:
FYI
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:
Fw: [dita] Proposal 13097 Stage 2 documentation update
Date:
Fri, 2 Aug 2013 14:58:12 -0400
From:
Michael Priestley <>
To:
Kristen James Eberlein
<>
FYI
Michael Priestley, Senior Technical Staff Member (STSM)
Total Information Experience (TIE) Technology Strategist
http://dita.xml.org/blog/25
----- Forwarded
by Michael
Priestley/Toronto/IBM on 08/02/2013 02:56 PM -----
From:
Daniel Dionne/Santa
Teresa/IBM@IBMUS
To:
Michael
Priestley/Toronto/IBM@IBMCA,
Date:
07/30/2013 01:36 PM
Subject:
Re: Fw: [dita]
Proposal 13097 Stage 2 documentation update
Michael and Robert,
Thanks for sending along Bob's
latest
efforts. I still have quite a few concerns. My analysis:
Basic content
The IBM
specialization contains
5 major elements
tsSymptoms
tsCauses
tsEnvironment
tsDiagnose
tsResolve
The OASIS design
contains only
four:
condition
cause
remedy
troubleSolution
The
only thing we are missing out on is <tsEnvironment>, which
Bob's
translation table suggests throwing in under <cause>.
Fair
enough. tsEnvironment is rarely used anyway, and the semantic
argument
that it really is a subcategory of causation makes sense. More
important
is the separation of diagnosis and resolution, which would both
be folded
in under <remedy>. But here's the mod entry for
<troublebody>:
<!--
LONG NAME: Troubleshooting
Body -->
<!ENTITY %
troublebody.content
"(%condition;?,
%cause;?,
%remedy;?,
%troubleSolution;*
)"
>
This says that <condition>, <cause>, and
<remedy> are
all optional, with only one allowed. That would mean that if we
migrated
from IBM, we could have either diagnosis or resolution, not
both. That's
unacceptable. Of course, there is also the wider model allowed
with
<troubleSolution>, which allows <cause> and
<remedy>
in any number and any order.
<!--
LONG NAME: Troubleshooting
Body division -->
<!ENTITY %
troubleSolution.content
"(%cause;|
%remedy;)*"
>
I must confess that
<troubleSolution>
seems very strange to me. We seem to have one model with fixed
contents,
but then include an alternate model with open contents.
Wouldn't
it be simpler to make <condition> required, or at least
first in
the sequence, but then allow any number of <cause> and
<remedy>
elements in any order? That would eliminate the dual model.
Element content
<condition> and
<cause>
are just sections, with no special content. No problems there.
<remedy> contains the full
task
model, which we don't handle because of our inheritance. Also,
it
contains a lot of options, in any number and order (including
<title>
in any order or number, which I would not have expected). So
yes,
we could accommodate our response role paragraphs with a title
and any
basic content. But there's no containment structure in
<remedy>,
which seems to me really necessary if it is to include different
actions
by different folks. <ResponsibleParty> is, I know, a
concession
to our model. But I don't really see how it is to be used, and
it's
not shown in the migration table. It can be thrown in anywhere
inside
<remedy>, so does it just put in a pseudo-title with no
containment
model?
--Dan Dionne
User Technology Solutions
Department: HHX
Silicon Valley Lab
Lotus Notes Address: Daniel Dionne/Santa Teresa/IBM@IBMUS
Internet Address:
Phone: 707-497-6554
Mobile: 408-250-6267
From:
Michael
Priestley/Toronto/IBM@IBMCA
To:
Daniel Dionne/Santa
Teresa/IBM@IBMUS,
Date:
07/30/2013 08:34 AM
Subject:
Fw: [dita] Proposal
13097 Stage 2 documentation update
FYI
Michael Priestley, Senior Technical Staff Member (STSM)
Total Information Experience (TIE) Technology Strategist
http://dita.xml.org/blog/25
----- Forwarded
by Michael
Priestley/Toronto/IBM on 07/30/2013 11:33 AM -----
From:
Bob Thomas
<>
To:
dita
<>,
Date:
07/30/2013 10:20 AM
Subject:
[dita] Proposal
13097 Stage 2 documentation update
Sent by:
<>
Hi,
I have updated the documentation for 13097, stage
2, to
incorporate feedback from last week's TC meeting. Unfortunately,
I did
not complete this task until yesterday. Consequently, the links
for 13097
in today's agenda points to stale versions of the documentation.
The new
links for 13097 are:
13097
PDF
13097
HTML
13097
DITA
Here is a summary of the changes made:
Added a "New elements" section that describes
each element
Changed the name of the
<troublebodydiv> element
to <troubleSolution> so that it will better connote
its intent
Changed the <troublebody> content model
so that
<troubleSolution> must be used for troubleshooting
scenarios having
multiple fallbacks
Added a new topic that discusses migration
considerations
for changing the IBM troubleshooting specialization base to
the new troubleshooting
topic
Regards,
--
Bob Thomas
+1 720 201 8260
Skype: bob.thomas.colorado
Instant messaging: Gmail chat ()
or Skype
Time zone: Mountain (GMT-7)
---------------------------------------------------------------------
To unsubscribe from this mail list, you must leave the OASIS TC that
generates this mail. Follow this link to all your TCs in OASIS at:
https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php
--
Bob Thomas
+1 720 201 8260
Skype: bob.thomas.colorado
Instant messaging: Gmail chat () or Skype
Time zone: Mountain (GMT-7)
Next in thread →
Next in month →