DITA Technical Communication SC

Re: Updated action on new troubleshooting topic

  • 1.  Re: Updated action on new troubleshooting topic

    Posted 08-05-2013 18:46
    Hi Dan, Thank you for your thoughts. I am sorry it took me so long to reply. I was on vacation from Wednesday until yesterday. The troublebody element As you said, the current structure for troublebody is: <!ENTITY % troublebody.content                        "(%condition;?,                           %cause;?,                          %remedy;?,                          %troubleSolution;* )" Two weeks ago, in response to feedback from the DITA TC, I modified it from: <!ENTITY % troublebody.content                        "(%condition;?,                           (%cause;                          %remedy;                          %troubleSolution;)* )"   I will ask the DITA TC to let me revert back to the previous model. The remedy element The remedy element includes the steps element and the steps-unordered element. Other task model elements, such as context and postreq, are not allowed. The inclusion of the steps element is an essential part of the troubleshooting topic proposal because the authoring community has expressed a strong desire to be able conref steps directly into troubleshooting topics. I believe that they would reject any proposal that did not include this capability. The wide availability of the title element in remedy is to maintain consistency with existing DITA models such as the content model for section. For authoring, I don't like this flexibility in section, condition, cause, or remedy. But, I didn't feel like the troubleshooting proposal was the right place to reconcile this issue. I understand your remark about responsibleParty not appearing in the migration table. responsibleParty is intended to be a specialization source for the IBM ts*Repsonse elements. Unfortunately for me, this exposes a design flaw. Namely, the new troubleshooting topic must declare responsibleParty to be a specialization of <p> rather than a specialization of <data>. Otherwise, we could have instances that would not parse in a new derivation of the IBM troubleshooting model. How do you feel about having responsibleParty inherit from topic/p? Your remark about containment has me concerned because the base model for section, from which remedy is derived, does not have a child that would be a suitable candidate from which to derive a containment element. Is this still an issue if we change responsibleParty to inherit from topic/p? I will be on the DITA TC call tomorrow morning. Meanwhile, I hope to hear back from you. I have an open calendar this afternoon if you wish to talk. I have added the tech comm subcommittee to the copy list on this in case they wish to interject. Best Regards, Bob On Wed, Jul 31, 2013 at 9:14 AM, Daniel Dionne < ddionne@us.ibm.com > wrote: Bob, Yes, good to hear from you--been too long.  Some comments on the specialization design thus far: The only thing we are missing out on is <tsEnvironment>, which your 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 would be a serious problem for us.   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: ddionne@us.ibm.com Phone: 707-497-6554 Mobile:   408-250-6267 Bob Thomas ---07/30/2013 08:34:31 AM---Hi Dan, It's been a year since we corresponded. I hope that you are doing well. From: Bob Thomas < bob.thomas@tagsmiths.com > To: Daniel Dionne/Santa Teresa/IBM@IBMUS, Date: 07/30/2013 08:34 AM Subject: Updated action on new troubleshooting topic Hi Dan, It's been a year since we corresponded. I hope that you are doing well. I wanted to make sure that you had the latest iteration of the stage 2 document for the troubleshooting topic. Please me send any feedback. Best 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) (See attached file: troubleshootingTopic_Feature13097_Phase2_Composite_29jul13.dita.pdf) -- 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)