Fwd: DITA 2.0 troubleshooting: commented examples for diagnostics with image plus steps

Additional information from Silke A at Ericcson.

    

    
Best,

      Kris

      

      Kristen James Eberlein

      Chair, OASIS DITA Technical Committee

      OASIS Distinguished Contributor

      Principal consultant, Eberlein Consulting LLC

      www.eberleinconsulting.com

      +1 919 622-1501; kriseberlein (skype)

      

      

    

    

      

      -------- Forwarded Message --------
      
        
          

            Subject:
            
            DITA 2.0 troubleshooting: commented examples for
              diagnostics with image plus steps
          

          

            Date: 
            Tue, 6 Jul 2021 12:29:41 +0000
          

          

            From: 
            Silke Achterfeld <>
          

          

            To: 
            Kristen James Eberlein
              <>
          

        
      
      

      

      
      
      
      
      

        
Hi Kris and the rest of DITA TC,

        
 

        
I promised to provide additional input for
          the troubleshooting topic discussion - sorry for the delay...

        
 

        
For those with only little time, the executive
              summary is really simple and really short:

        
 

        
I can see situations in which you would
          like to include both an image and diagnostic steps in the
          Diagnostics part of a troubleshooting topic.

        
With the current plans for DITA 2.0, this
          is not possible - but the way I see it, it could easily be
          made possible by allowing both of the child elements of the
          new <diagnostics> element, and not just one or the
          other.

        
 

        
--------- Here's where the longer
              part with the example(s) starts:

        
 

        
Today, we would create one
          <troublesolution> and we would add an
          @outputclass="diagnostics" to it - for our processor to know
          that the rendering should be different than for the 'normal'
          <troublesolution> elements.

        
 

        
We use <cause> for the flowchart
          image (or any diagnostics information that is not a sequence
          of steps), and we use <remedy> for the list of
          diagnostic steps.

        
That would actually map pretty nicely to
          the 
            <diagnostics-general> and <diagnostics-steps>
            that you have planned for DITA 2.0.

        
 

        
However, in contrast to
            what's in your plans, we might have situations in which we
            need both: a flowchart image
            plus a list of steps.

        
 

        
Below, please find an example that we have
          used in our internal guidelines where we would need both

          - I omitted the XML source that my colleague used for that,
          it's a bit all over the place, I only noticed now, when I
          wanted to copy it ... ;-)

        
 

        
The flowchart image can be very helpful to
          see the required steps at a glance, and there might be users
          who understand immediately what needs to be done for the
          decisions in those two diamond shapes. The blue boxes in the
          flowchart can be created as a clickable area, thus, taking
          users directly to where they need to go for the solution.

        
 

        
However, there might be users who do not
          know what to do to be able to answer the questions in the
          diamonds with yes or no.

        
They need a written form of the diagnostic
          steps, which would tell them how to check connectivity, or how
          to analyze the DNS entries.

        
 

        
So, for the troubleshooting topic, we would
          need the image 
            plus the steps.

        
I believe that the fix could be relatively
          simple, by allowing both
          <diagnostics-general> and
            <diagnostics-steps> to be used in one troubleshooting
            topic (at the moment, it is 'either... or')

        
 

        
In some of the e-mail
              conversation about this topic, Elliot Kimber had the idea
              of somehow allowing images to be added before the steps in
              <diagnostic-steps>, but unless you had a very
              specific reason that I don't see for requesting to have
              only one of the elements <diagnostics-general> or
              <diagnostics-steps>, I think the most simple and
              straightforward solution would be to allow both elements
              to be used together.

        
 

        
 

        

        
 

        
 

        
Let me add one more example to illustrate
          the need - the one from the White paper that I had mentioned
          already earlier, but this time, I'll spend some more words to
          explain my thoughts. It's the 'complex scenario' in the DITA
          1.3 white paper, starting on page 14.

        
 

        
Basically, the scenario and the resulting
          XML structures are similar (which is not a big surprise, as we
          based our guidelines on the White paper ;->).
          

        
I am including a few screen shots below,
          for your reference.

        
 

        
- There's a <troublesolution> with a
          flowchart in the <cause> and some diagnostic steps in
          the <remedy> that describe the diagnostic actions
          required for the decisions in the diamond shapes.

        
 

        
- So, even the structure that you once
          suggested to use for troubleshooting topics wouldn't work with
          the current plans of DITA 2.0... ;-)

        
 

        

        

        

        
 

        
 

        
Thanks for looking into this!

        
 

        
Regards,

        
Silke

        
 

        
 

        

        
 

        
Silke
              Achterfeld

        
Principal
            Technical Writer

        
 

        
Developer

        
BDGS
            SA BSS PDU BSS PDG EB BSCS Dev 1

        
Phone:
            +492115341088

        


        
 

        
Ericsson

        
Herriotstr.
            1

        
60528,Frankfurt
            am Main

        
Germany

        
ericsson.com

        
 

        

        
 

        
Our
            commitment to
            
              Technology for Good
            and 
              Diversity and Inclusion
            contributes to positive change.

            Follow us on: 
              Facebook 
              LinkedIn 
              Twitter

            

            Legal entity:ERICSSON
            TELEKOMMUNIKATION GMBH
            registration number
          HRB
            97397,
            registered office in
          Frankfurt.

            This communication is confidential. Our email terms: 
              www.ericsson.com/en/legal/privacy/email-disclaimer