dita — archive

Stan's e-mail comments re troubleshooting

From: Kristen Eberlein
To: [email protected]
Date: Mon, 13 Feb 2023 17:38:00 -0000

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 [email protected] Skype: kriseberlein; voice: +1 (919) 622-1501 From: Default <[email protected]> Sent: Thursday, February 9, 2023 4:51 PM To: Kristen James Eberlein <[email protected]> Cc: DITA Technical Committee ([email protected]) <[email protected]> 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 [email protected] Skype: kriseberlein; voice: +1 (919) 622-1501 From: [email protected] < [email protected] > On Behalf Of Kristen James Eberlein Sent: Wednesday, February 8, 2023 1:58 PM To: Dr. Stanley Doherty < [email protected] >; [email protected] 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 [email protected] Skype: kriseberlein; voice: +1 (919) 622-1501