I agree with Silke’s criticism and also Bob’s proposal for the diagnosis element and making troubleSolution optional. I think these additions will help to address the issue.
Thanks and best regards,
--Scott
Scott Hudson
Content Strategist
Digital Aviation Learning & Development
Voting member:
OASIS DocBook TC, Publishers SC
OASIS DITA TC, Tech Comm SC, LW DITA SC, Learning Content SC
OASIS Augmented Reality in Information Products (ARIP) TC
Jeppesen
Digital Aviation Boeing
55 Inverness Drive East Englewood,
CO 80112
www.jeppesen.com This document contains only administrative, uncontrolled data under U.S. International Traffic in Arms Regulations.
From: <
dita-techcomm@lists.oasis-open.org > on behalf of Bob Thomas <
bob.thomas@tagsmiths.com >
Date: Thursday, December 29, 2016 at 8:02 AM
To: Kristen James Eberlein <
kris@eberleinconsulting.com >
Cc: "
dita-techcomm@lists.oasis-open.org " <
dita-techcomm@lists.oasis-open.org >, Silke Achterfeld <
silke.achterfeld@ericsson.com >
Subject: [dita-techcomm] Re: DITA 1.3 troubleshooting topic: missing a good place for diagnostic steps...
Silke's criticisms of the troubleshooting model and of the whitepaper are valid. The code example in the whitepaper is wrong. It represents my original thinking about how to handle diagnosis. Later, I determined that it would be better to use troublesolution for
diagnosis so that writers would have access to steps through remedy. Like Silke, I am not satisfied with this solution. But, with the current model, that is the best that we can do.
I would like to make a couple of backward-compatible changes to the troubleshooting model for the next release of the technical communications package.
Add a new optional diagnosis element to the model right after condition. This element would be a specialization of section that includes the steps element from task. Silke's observations, plus the complex scenario in the whitepaper, justify this change.
Make the troublesolution element optional rather required. For some complex scenarios, it makes sense to have a troubleshooting topic as a parent topic for child task topics. That way the semantics of the condition element, and now the diagnosis element,
could be used in this parent topic without having to deal with a mandatory troublesolution element.
If anyone has thoughts about any of this, please share them.
Best Regards,
Bob Thomas
On Thu, Dec 29, 2016 at 5:40 AM, Kristen James Eberlein
<
kris@eberleinconsulting.com > wrote:
Forwarding on an e-mail from a colleague at Ericcson ...
Best,
Kris
Kristen James Eberlein
Chair, OASIS DITA Technical Committee
Principal consultant, Eberlein Consulting
www.eberleinconsulting.com +1 919 682-2290 ; kriseberlein (skype)
-------- Forwarded Message --------
Subject:
DITA 1.3 troubleshooting topic: missing a good place for diagnostic steps...
Date:
Wed, 28 Dec 2016 17:10:41 +0000
From:
Silke Achterfeld
<silke.achterfeld@ericsson. com>
To:
kris@eberleinconsulting.com <
kris@eberleinconsulting.com>
Hi Kris,
When we met at DITA Europe in Munich, back in November, I mentioned that I might be sending one or the other question or comment on the DITA spec.
Well, as always, I never really came round to doing that... -- but in recent discussions about how we could implement the new troubleshooting topic for our content we came across an issue that I would like to bring up
with you:
If we need to document troubleshooting steps for a rather complex scenario, in which diagnostic steps are required to identify what the actual 'condition' in question is at all, we are missing a specific element for storing
these diagnostic steps...
For the diagnostic steps, we would like to create a flowchart (with hyperlinks/hotspots or whatever you might call them) and to have a linear sequence of steps to go with that, as suggested in the White paper on Troubleshooting
as well.
Funnily, that White paper is not quite consistent regarding where to put that kind of information either:
-- The sample troubleshooting topic has this kind of information in the first <troubleSolution> element
-- The sample topic template at the end (that is provided as a codeblock for copy-and-paste) includes instructions that the diagnostic steps should go into the <condition> element...
We have looked at both options more closely - and I must say that we are not happy with any of the two:
-- If we use <condition> for the diagnostic steps (and maybe also a flowchart with hotspots), we would have to create a 'pseudo-steplist' for the linear sequence of steps, using an ordered list (something you actually
should never do! -- and if we start doing that in our 'official' templates, writers might start to do similar things in other places as well ...)
-- If we use a <troublesolution> element, we need to include a description and a flowchart in the <cause>; and put the steps in the <remedy>.
However, this does not feel right either, because it is violating the DITA principle to use semantic tagging, isn't it? (... the information is neither cause nor remedy...).
Do you have an idea how others are dealing with this situation?
Can you remember why you decided not to have a specific element for diagnostic steps?
Thanks in advance for your feedback!
All the best for 2017,
Silke
SILKE ACHTERFELD
Principal Technical Writer
BICP PADB PL RM & CM DU C&B
Ericsson
Herriotstr. 1
60528 Frankfurt, Germany
Phone +49 69 2383 3825
silke.achterfeld@ericsson.com www.ericsson.com Legal entity: Ericsson Telekommunikation GmbH, registered office in Frankfurt. This Communication is Confidential. We only send and receive email on
the basis of the terms set out at
www.ericsson.com/email_ disclaimer
--
Bob Thomas
+1 720 201 8260
Skype: bob.thomas.colorado
Instant messaging: Gmail chat (
bob.thomas@tagsmiths.com ) or Skype
Time zone: Mountain (GMT-7)