In his e-mails last week, Stan spoke against “mixing diagnostic, cause identification, and remedy information together” in the diagnostics section of the troubleshooting topic. He stated “Diagnostic elements should reference possible causes,
therefore, but never remedies. Our write-up for <diagnostic-general> moves freely between cause, diagnostic, and remedy information.”
I will note that the examples of <diagnostics-general> elements came from the DITA 2.0 stage two and stage three proposals, and so were approved by the TC. (Stan, you voted “yes” on both the stage two and three proposals.) Of course, if
we now can see problems with the examples that can be addressed, we should do so.
Here is the screen capture from the <diagnostics-general> topic, as it entered review:
Stan, I’ve updated the content of the code block and resulting screen capture of how a <diagnostics-general> element might be rendered. Do these small changes handle your concerns?
Note that all the <troubleSolution> elements in this example topic contain only <remedy> elements with titles that conkeyref in <steps>. There are no <cause> elements to link to.
Stan, are there other examples where you think there is egregous admixture of diagnostic, cause identification, and remedy content? The possible examples that I am aware of are the following:
- 1.1 Troubleshooting, figure 2
- 2.1 <cause>, example
- 2.5 <diagnostics-steps>: Last step in the example?
- 2.6 <remedy>: Content of <cause> element
- 2.9 <troubleshooting>: Content of <cause> element
Best,
Kris
Kristen James Eberlein
Chair, OASIS DITA Technical Committee
Owner, Eberlein Consulting LLC
kris@eberleinconsulting.com
Skype: kriseberlein; voice: +1 (919) 622-1501