OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

dita-techcomm message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]


Subject: Fwd: DITA 1.3 troubleshooting topic: missing a good place for diagnostic steps...


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

 

 

 

Ericsson

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



http://www.ericsson.com/current_campaign

 

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

 



[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]