See some comments below. Stan, thanks for starting this conversation.
Best,
Kris
Kristen James Eberlein
Chair, OASIS DITA Technical Committee
Owner, Eberlein Consulting LLC
kris@eberleinconsulting.com
Skype: kriseberlein; voice: +1 (919) 622-1501
-----Original Message-----
From: dita@lists.oasis-open.org <dita@lists.oasis-open.org> On Behalf Of Dr. Stanley Doherty
Sent: Wednesday, February 8, 2023 9:48 AM
To: dita@lists.oasis-open.org
Subject: [dita] Troubleshooting discussion topics
Hi --
I spent some quality time last evening with the troubleshooting section of the spec. I found it to be confusing in general and self-contradictory in places.
Outside some line edits that I will enter today (hopefully), the majority of the comments that I have relate to some general issues. I thought it better to raise the general issues in a separate email.
1. Troubleshooting logic #1: The current spec makes frequent use of the phrase "cause and remedy pairs". Simple symptom-solution pairs rarely need dedicated troubleshooting topics, so leading with the notion of "pairs" is confusing. The spec is right on
when it describes in the overview topic that cause/remedy logic may have any combination of many-to-many, many-to-one, or one-to-many relationships. The power of the DITA troubleshooting elements is the ability to shape the diagnostic, cause, and remedy sections
to multiple content models. The repeated references to "cause and remedy pairs" creates the impression that 1:1 cause/remedy pairs are the norm versus the rare exception. The troubleshooting blocks for diagnostics, cause, and remedy have no default correlations.
They are merely building blocks.
<kje>We'll certainly have to look at this. In general, I think cause and remedy pairs were DITA 1.3 spec language used to refer to the content of a <troublesolution> element. Note that the content model of <troublesolution> must be one
of the following:
- <cause>, <remedy>
- <cause>
- <remedy>
</kje>
QUESTION: Do we want to preserve the "pairing" logic or move to a "building block" logic?
2. Troubleshooting logic #2: Before customers can identify one or more causes for a symptom, they need to diagnose the root cause. Logically. diagnostic content would need to precede cause identification. Diagnostic elements should reference possible causes,
therefore, but never remedies. Our write-up for <diagnostic-general> moves freely between cause, diagnostic, and remedy information. A complete example would be sequenced as diagnostics -> causes -> remedies. That's how we roll when we contribute to Support
KB articles.
QUESTION: Do we want to be rigorous semantically about the contents of cause, diagnostic, and remedy sections? No admixture.
<kje>Stan, IF I UNDERSTAND YOU CORRECTLY, this would really break the design of diagnostics as we added it in DITA 2.0, I think. Especially the <diagnostics-general> element, which was designed to accomplish something exactly like what
we outline in the example for 2.4 <diagnostic-general>. Is that example what you are objecting to?</kje>
3. Consistent terminology:
- Problem? Condition? Symptom? Situation?
- Problematic? Undesirable?
- Cause and symptom?
- Root causes and contributory causes?
<kje>Iâm always all in for consistent terminology.</kje>
QUESTION: Do we need a mini-glossary here?
4. Integration with Support and community content: For complex software and hardware systems, tech writing teams rarely document low-frequency or edge-case troubleshooting. Support and field people develop that content and capture it in knowledgebases.
Pointing off the DITA procedures that offer overly-simple remedies makes assumptions about the scope of customer-facing documentation. Providing an example or two of links to Support or Community remedies would be nice.
<kje>While we could refer to a support knowledge base in one of the examples, the larger issue that you reference is well outside of the scope of the spec. It might or might not be appropriate for the Troubleshooting committee note.</kje>
QUESTION: Should we recognize and promote the collaborative aspects of the troubleshooting domain?
5. Chatbots: One of our greatest strengths with DITA and, especially, with the troubleshooting domain is its ability to feed sophisticated semantic markup into machine learning technologies. Worth mentioning somewhere?
<kje> Well outside of the scope of the spec. It might or might not be appropriate for the Troubleshooting committee note, depending on how we shape it. Remember our first priority for the Troubleshooting committee note is simply to bring
it up-to-date for DITA 2.0. @Stan, are you interested in becoming an author for the committee note?.</kje>
I'll enter the edits that are unrelated to these discussion topics.
Stan