Thoughts about troubleshooting and diagnosis

[Kristen James Eberlein <kris@eberleinconsulting.com>]

I've been re-reading the DITA Adoption TC whitepaper about troubleshooting. It was authored by Bob Thomas. A couple of thoughts:

• The DITA TC must issue an updated committee note about troubleshooting with DITA 2.0, and the 1.3 Troubleshooting article should be marked as obsolete and retired.
• The DITA 1.3 Troubleshooting white paper was authored in DITA; we need to track down the source.

Within the white paper itself:

• Managing complexity > Resolving complex problems: Mentions diagnosis
• Managing complexity > The troubleshooting topic and complexity: States that diagnostic information should be placed in the first <troublesolution> element in the topic. The example shows the diagnostic information is placed within a <cause> element with a title that highlights its diagnostic nature: "Determine the cause." The <cause> element then contains a paragraph and an image; the image is a flow chart that illustrates the steps placed within the <remedy> element. THIS IS THE IMAGE THAT SILKE AT ERICSSON POINTED US TO.

So, even in the 1.3 time frame we were anticipating the need for diagnostic information, although perhaps the solution proposed in the troubleshooting white paper was less than optimal.

--
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)