Comments from Dan Dionne about the troubleshooting topic proposal (13097)

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)