Troubleshooting discussion topics

["Dr. Stanley Doherty" <stan@modularwriting.com>]

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