FW: DITA 2.0 troubleshooting: diagnostics_general OR diagnostics_steps (not both)?

[Dawn Stevens <dawn.stevens@Comtech-serv.com>]

Hi all,

I received this email Monday from Ericsson with regard to the Diagnostics proposal. I recall that we briefly had a discussion about whether <diagnostics> should allow only one or both or more than one of <diagnostics_general> and <diagnostics_steps> and determined that only one was necessary. Here is now the use case that argues for both.

 

Should we revisit that decision now before we start wrapping things up?

 

Best,

Dawn

 

From: Silke Achterfeld <silke.achterfeld@ericsson.com>
Date: Monday, May 17, 2021 at 7:57 AM
To: Dawn Stevens <dawn.stevens@Comtech-serv.com>
Subject: DITA 2.0 troubleshooting: diagnostics_general OR diagnostics_steps (not both)?

Hi Dawn,

 

I need to get back to troubleshooting topics and the changes that will come with DITA 2.0:

 

If I understood it correctly, you would use either <diagnostics_general> or <diagnostics_steps>.

 

However, if you wanted to have a flowchart that shows the decision tree, you would need <diagnostics_general> to do that, and you might need a step list in addition to that to give some further explanation  about the individual steps described in the boxes of the flowchart (for example, to add some command samples or so). I'm not saying that we will have a lot of these situations -- it's just that in our current guidelines for writing troubleshooting information, we have exactly that: a flowchart + step list (in cause/remedy), and I have noticed that the troubleshooting whitepaper (starting at p.14) suggests to do the same thing ...

 

If I understood the proposal for DITA 2.0 correctly, those structures would not be allowed anymore, would they?

 

Thanks in advance for your clarification!

 

Regards,

Silke