Comments from Dan Dionne about the troubleshooting topic proposal (13097

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 <mpriestl@ca.ibm.com>
To:	Kristen James Eberlein <kris@eberleinconsulting.com>

FYI

Michael Priestley, Senior Technical Staff Member (STSM)
Total Information Experience (TIE) Technology Strategist
mpriestl@ca.ibm.com
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
1. tsSymptoms
2. tsCauses
3. tsEnvironment
4. tsDiagnose
5. tsResolve
The OASIS design contains only four:
1. condition
2. cause
3. remedy
4. 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>:

<!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.

<!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: ddionne@us.ibm.com
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
mpriestl@ca.ibm.com
http://dita.xml.org/blog/25
----- Forwarded by Michael Priestley/Toronto/IBM on 07/30/2013 11:33 AM -----

From: Bob Thomas <bob.thomas@tagsmiths.com>
To: dita <dita@lists.oasis-open.org>,
Date: 07/30/2013 10:20 AM
Subject: [dita] Proposal 13097 Stage 2 documentation update
Sent by: <dita@lists.oasis-open.org>

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:

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 (bob.thomas@tagsmiths.com) or Skype
Time zone: Mountain (GMT-7)

dita message