[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: RE: [dita] Troubleshooting discussion topics
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 Skype: kriseberlein; voice: +1 (919) 622-1501 From: dita@lists.oasis-open.org <dita@lists.oasis-open.org>
On Behalf Of Kristen James Eberlein 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 -----Original Message----- 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:
</kje> 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> 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> I'll enter the edits that are unrelated to these discussion topics.
Stan |
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]