dita — archive

Fwd: [dita] FW: DITA 2.0 troubleshooting: diagnostics_general OR diagnostics_steps (not both)?

From: Eliot Kimber <[email protected]>
To: [email protected]
Date: Tue, 22 Jun 2021 16:14:00 -0000

Looking at the original paper and Silke s comments, my first impression is that there is not a clear distinction between cause and remedy in the complex example but then looking at it more deeply I think the problem is really that there needs to be nested troubleshooting topics, one for each actual cause determined via the flow chart. I read the flowchart as use this flow chart to determine the cause , which suggests it s appropriately in the cause section, but then the steps, which are in the remedy section, repeat the spreadsheet, so they are again really telling you how to determine the cause of the problem and thus cannot be the remedy. I do not see any remediation information that you could then perform in response to having determined the cause via the flowchart and steps, but that may simply be because it was omitted from the example. It feels like there s a feature missing, namely some form of complex cause determination component. But in general reading it now, I m not at all happy with how the sample content was mapped to the troubleshooting markup in the paper it doesn t seem to be a good fit. The example represents a number of distinct causes, each one of which presumably has its own remediation steps. Thus, I would expect to have a top-level topic that represents the cause ( insufficient voltage alarm ), describes the process for determining the specific cause, and then in the remedy section has a statement to the effect of See the following cause-specific troubleshooting topics for each possible cause . For each cause as determined by the flow chart you then have a nested troubleshooting topic for that specific cause (i.e., Faulty LN243 pack or Excessive line noise). The only change that might suggest is that <cause> should allow <steps> but I haven t thought that through. Cheers, E. -- Eliot Kimber http://contrext.com From: <[email protected]> on behalf of Kristen James Eberlein <[email protected]> Date: Tuesday, June 22, 2021 at 7:23 AM To: DITA TC <[email protected]> Subject: Fwd: [dita] FW: DITA 2.0 troubleshooting: diagnostics_general OR diagnostics_steps (not both)? Info from Silke Achterfeld about troubleshooting requirements. I also asked her for another example. 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: RE: [dita] FW: DITA 2.0 troubleshooting: diagnostics_general OR diagnostics_steps (not both)? Date: Tue, 8 Jun 2021 14:54:03 +0000 From: Silke Achterfeld <[email protected]> To: Kristen James Eberlein <[email protected]> Hi Kris, I realized that I let lots of other items on my to do list get in the way and now the next meeting of the DITA TC is about to start ... :-o To look at an example of the situation that I described in my e-mail to Dawn, you could even turn to the troubleshooting whitepaper ( https://www.oasis-open.org/committees/download.php/53516/DITA13TroubleshootingArticle_FINAL_03jul14.pdf ), section "Complex Scenario" In there, you will find a flow chart followed by a sequence of steps that explain the boxes in the flowchart in more detail. Hope this helps. Let me know if you would like a more elaborate and less rushed description of the situation to be used in another meeting, not as 'short notice' as this one :-) Regards, Silke