Stan's e-mail comments re troubleshooting

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

Skype: kriseberlein; voice: +1 (919) 622-1501
From: Default <>
Sent: Thursday, February 9, 2023 4:51 PM
To: Kristen James Eberlein <>
Cc: DITA Technical Committee () <>
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

Skype: kriseberlein; voice: +1 (919) 622-1501
From:  < 
> On Behalf
Of Kristen James Eberlein
Sent: Wednesday, February 8, 2023 1:58 PM
To: Dr. Stanley Doherty <  >;

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


Skype: kriseberlein; voice: +1 (919) 622-1501