More re troubleshooting discussion topics

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

Hey, Stan, I just wanted to follow up with another response to this e-mail. You stated "Simple symptom-solution pairs rarely need dedicated troubleshooting topics," and I disagree. I think it really depends on the audience. In my experience, such simple troubleshooting topics are quite useful for internal team documentation and tech doc user documentation.

I've created A LOT of such topics when I've documented procedures for implementations that I've work on, especially small teams where I've played a significant mentoring role. Scanning through the source, I can see that many of the topics deal with the CCMS or version control. For example, when you know that team members are regularly going to run into problems when LDAP passwords expire and they need to update passwords that are stored in a Git client, it's a solid investment against frustration/friction to author a topic about the issue.

I also think that simple, dedicated troubleshooting topics are wonderful replacements for the old-school approach of putting lots of troubleshooting items in a table. Having the items in dedicated troubleshooting topics enables reuse; it also can feed chatbots and better enable self service. (Stylesheets can always render them in a tabular format, if that's what a company wants for some output formats.)

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.   

  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.  
     
3. Consistent terminology:
   - Problem? Condition? Symptom? Situation?
   - Problematic? Undesirable?
   - Cause and symptom? 
   - Root causes and contributory causes? 
   
   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. 

   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? 

I'll enter the edits that are unrelated to these discussion topics.     
   
Stan