Last week Stan raised some important points about the current draft of the troubleshooting topics. Iâve attempted to summarize and respond to them below. (Stan, I hope my summaries do not obscure finer points of your original e-mail.)
Cause and remedy pairs
Summary: This is terminology that creates the impression that 1:1 cause/remedy pairs are the norm rather than the rare exception.
Eberlein: Iâve made a pass through all the topics to remove this terminology, except for the rare places where it is accurate.
Mixing diagnostic, cause, and remedy information together
Summary: Diagnostic content should precede identification of causes; it should not contain remedy information.
Eberlein: I will send a separate e-mail to the TC about this.
Need for more precise and consistent terminology
Summary: The terminology used in the topics is overlapping and inconsistent, for example:
- Problem? Symptom? Condition?
- Problematic? Undesirable?
- Root causes and contributory causes?
Eberlein: In my edits, Iâve done my best to more consistently use the same terms in the topics. I think this goal will be fully achieved with a second review and editorial pass. (And I think that probably distinguishing between root
and contributory causes is out-of-scope for the spec examples.)
Integration with Support and community content
Summary: Complex (edge-case) troubleshooting is typically developed by support and field service reps who capture it in knowledgebases. Should we recognize and promote the collaborative aspects
of the troubleshooting topic?
Eberlein: Stan, what are you asking that we change in the spec? I think focusing on collaboration across the enterprise focusing on troubleshooting is more in scope for the committee note.
Chatbots and AI
Summary: One of our greatest strengths with DITA and the troubleshooting topic is its ability to feed sophisticated
semantic markup into machine learning technologies. Is this worth mentioning somewhere?
Eberlein: I think this content is out-of-scope for the spec, but perfectly appropriate for the troubleshooting committee note, assuming that we have TC members (looking at you, Stan!) willing to work on it.
Best,
Kris
Kristen James Eberlein
Chair, OASIS DITA Technical Committee
Owner, Eberlein Consulting LLC
kris@eberleinconsulting.com
Skype: kriseberlein; voice: +1 (919) 622-1501
From: Default <stan@modularwriting.com>
Sent: Thursday, February 9, 2023 4:51 PM
To: Kristen James Eberlein <kris@eberleinconsulting.com>
Cc: DITA Technical Committee (dita@lists.oasis-open.org) <dita@lists.oasis-open.org>
Subject: Re: FW: [dita] Troubleshooting discussion topics
Thanks for the feedback, Kris. I have a few follow-up comments below.
Stanley Doherty, Ph.D. Member - OASIS DITA Technical Committee ModularWriting.com
On 2023-02-09 09:39, Kristen James Eberlein wrote:
Stan, I think you are right, and that this set of content needs to be
edited with an eye to removing the âcause and remedy pairâ focus.
Best,
Kris
Kristen James Eberlein
Chair, OASIS DITA Technical Committee
Owner, Eberlein Consulting LLC
kris@eberleinconsulting.com
Skype: kriseberlein; voice: +1 (919) 622-1501
From: dita@lists.oasis-open.org <dita@lists.oasis-open.org> On Behalf
Of Kristen James Eberlein
Sent: Wednesday, February 8, 2023 1:58 PM
To: Dr. Stanley Doherty <stan@modularwriting.com>;
dita@lists.oasis-open.org
Subject: RE: [dita] Troubleshooting discussion topics
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>
<sdoherty>
Yes - there may be a misalignment between our XML logic and overall content logic.
</sdoherty>
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>
<sdoherty>
Yes -- if we are rigorous about semantic containment, the markup focused on diagnostics, cause(s), and remedies should be distinct.
</sdoherty>
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>
<sdoherty>We may have one of those chicken-and-egg situations. Without realistic use cases for the troubleshooting domain, it may not enlist much of a following. Without a following,
a separate Committee Note may not have much of an audience.</sdoherty>
I'll enter the edits that are unrelated to these discussion topics.
Stan