Re: [dita] Feedback on the updated troubleshooting tech paper

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

Hi, Stan.

I think you raise good poins, but I think they might be outside the bounds of a committee note that is focused on the MECHANICS of the troubleshooting topic. What do others think?

Perhaps we could include a few more contextual topics, such as:

• The role that troubleshooting information can play in fostering collaboration across the enterprise
• The need to work with technical support, customer support, and field sales organizations before adopting an XML content model for troubleshooting

But I think the focus of this committee note should largely be: Here is the troubleshooting topic that the DITA TC ships, here's what you can do with it, and here are some best practices. We probably would NOT be planning to other and publish this committee note if DITA 2.0 really makes the practises advocated in Bob Thomas's original whitepaper obsolete

I think the points that you raise in #2 are strategic in nature. Excellent and important, but maybe not appropriate something we can really cover in this committee note. They really deal with what a company should do at the onset of considering troubleshooting content in their documentation. How should a group get started with developing troubleshooting information?

#3 is largely about why one would want to encourage specialization -- or tweaking the authoring interface to rename elements to match a company's current Knowledgebase fields. I know I usually encourage companies to AT LEAST create document-type shells for troubleshooting topics, so that the shells can include constraints to tighten the content model for the author. In general, the content model of troubleshooting is SO relaxed (to cover many different use cases) that I think it is difficult to authors use OOB. So much relies on having decent titles for critical sections -- whether the titles are authored or labels generated by the style sheets. Without creating a few different document-type shells, the rendered output tends to be horribly inconsistent.

#4 emphasizes the need for good integration work and (again) specialization.

And your last point -- using the OOB troubleshooting topic as a starting point in conversations with stakeholders to consider how to handle troubleshooting information across the enterprise -- is another good one. I've certainly done this, and when I asked about usage of the troubleshooting topic on dita-users recently, it was a scenario mentioned by another DITA architect/specialist.

So many excellent points, but some (I think out-of-scope) with what we can do with this troubleshooting committee note. We've got a lot on our plate already ...

Would you be interested in being a co-author of this committee note? And if you want to collaborate on an article with more of a strategic focus (for an TBD publishing outlet), I'd be game for that.

I will say, I wonder how many companies are actually using the troubleshooting topic. I did not get many responses when I pinged folks on dita-users. I suspect that this is because of the barriers to using it OOB:

• Need for good stylesheet support (and the lack of it in the DITA-OT)
• Need for rigorous authoring templates -- or document-type shells -- to make the topic useful for authors.
• Need for specialization if collaboration outside of the technical documentation department is a priority
• Fact that many techdoc departments are accustomed to delivering troubleshooting information in a tabular format

All of these barriers are points that Dawn, Nancy, and I want to cover in the committee note. We think that the troubleshooting topic is a useful structure (especially given its ability to use <steps>!) but that it has fared challenges in adoption for the reasons that I mention above.

Best,
Kris

Kristen James Eberlein
Chair, OASIS DITA Technical Committee
OASIS Distinguished Contributor
Principal consultant, Eberlein Consulting LLC
www.eberleinconsulting.com
+1 919 622-1501; kriseberlein (skype)

On 9/27/2021 3:54 PM, Dr. Stanley Doherty wrote:

> This is a worthwhile revision of the original tech paper . . . my compliments. 
>
> I have a few friendly suggestions to consider for addition:
>
> 1. Collaboration gateway: Individual troubleshooting topics are certainly 
>    useful, but the real value of investing in focused troubleshooting 
>    content has lots more to do with collaboration across 
>    organizational barriers than building out some separate library
>    of documentation topics. Organizations that are large enough to 
>    consider DITA certainly have technical support, customer support, 
>    or field sales organizations who have been developing diagnostic
>    and troubleshooting information for years. Whatever the tech pubs
>    team might think are useful XML content models for troubleshooting
>    information is secondary to leveraging the logic and substance of
>    existing troubleshooting content developed in other organizations. 
>    
> 2. First steps: Section 3 of the tech paper doesn't mention the 
>    primary business justification for developing troubleshooting
>    content -- reducing the number of customer support calls. IAs 
>    and managers planning to develop an initial library of 
>    troubleshooting topics should buy the head of customer 
>    support lunch and ask her/him for a list of the 50 most
>    frequent support issues. Some 30 or so issues are most certainly
>    suitable to be worked into DITA troubleshooting topics. It's 
>    a win-win. Support can now feed the tech pubs team all sorts of
>    field-tested content and the writing group can get on the 
>    scoreboard with some proven content. Rewriting existing Support 
>    content also helps writing teams shake out their XML templates
>    and metadata. Not every writer is is strong in this area, so
>    managers need to vet the writers as well as the writing. 
>    
> 3. Collaborative design: Under the hood of the most popular
>    knowledge managements systems supporting KCS
>    (Knowledge-Centered Support), you find very similar fields
>    and views for diagnosing and solving customer issues. Adding 
>    yet another set of fields (XML element names) on top of 
>    the existing ones doesn't make that much sense. Why not 
>    recast the DITA content models to adopt the names of the 
>    KCS fields that are already familiar to the organization. 
>    Yes, there would be little consistency between the XML
>    troubleshooting elements in Company-A or Company-B, but
>    so what?  
>    
> 4. Structured information exchange: Most any engineering 
>    grad student would be able to write converters between
>    structured database records in KCS systems and DITA
>    XML troubleshooting topics (especially if they share 
>    many of the same field/element names). Similarly, adding
>    adding specialized DITA elements that correspond or
>    link to non-DITA support or escalation tickets would
>    be huge. DITA troubleshooting content should be an 
>    extension of a corporate content strategy around 
>    troubleshooting information. Finding ways to emphasize
>    that role in the tech paper would be good.  
>    
> Using the troubleshooting topic type as a calling card for 
> collaboration and not as an end in itself makes business
> sense. DITA is late to the party. It has been easier for
> Support organizations to publish troubleshooting information
> or FAQs out of their KCS systems than to educate tech pubs
> organizations on how to develop and curate enterprise-class
> support information. 
>
> DITA is quite capable of playing nicely in this collaborative space (perhaps a different tech paper). 
>
> Let's play to our strengths where we can. 
>
>
>  
>     
>       
>