Fwd: DITA 2.0 troubleshooting: commented examples for diagnostics with i

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

silke.achterfeld@ericsson.com

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

dita message