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


Help: OASIS Mailing Lists Help | MarkMail Help

dita message

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

Subject: Re: [dita] Diagnostics for Troubleshooting Topic

Hi Dawn,


This is very good timing. I was approached by one of our developers recently with some troubleshooting scenarios that are difficult to fit into the current model. Please see that attached diagrams. The red highlighting indicates the gap and how we are addressing this today (less than ideal).


I would be very interested in helping or reviewing this proposal.


Thanks and best regards,



Scott Hudson
Content Technology Strategist, DS&A Information and Knowledge Services

Jeppesen, A Boeing Company

55 Inverness Drive East

Englewood, CO 80112

303-328-6228 | Cell: 303-350-7934







From: <dita@lists.oasis-open.org> on behalf of Dawn Stevens <dawn.stevens@Comtech-serv.com>
Date: Friday, November 8, 2019 at 2:00 AM
To: dita <dita@lists.oasis-open.org>
Subject: [dita] Diagnostics for Troubleshooting Topic


I would like to start work on the pending Stage 1 issue âDiagnostics for Troubleshooting Topicâ (no issue number is assigned yet).

My proposal is change <troublebody> to include a new, optional element, <diagnostics> as follows:

(<condition>?, <diagnostics>?, <troubleSolution>+)?

This element is needed in situations where a single condition has multiple causes, each of which has a unique remedy. In many of these cases, the user does not know why the condition is happening and needs guidance for determining which of the many reasons is their specific problem before they can start to follow the appropriate remedy steps.

Currently, my clients in this situation are forced to use a <cause> or <remedy> element within a <troubleSolution> section and use the <title> element of that section to call it âDiagnosticsâ (or similar). After explaining how to determine what the cause actually is, they add further <troubleSolution> elements as intended to pair individual causes with their remedies. While it works, it is not semantic, and is clearly a workaround.

The reason clients may choose between cause and remedy is that this type of diagnostic information may be approached in a couple of different ways:

1 â Often the diagnostic information is a table or flow chart figure to determine what is the cause. In this case, they use the <cause> section or a <steps-informal> in <remedy>.

2 â In other cases, the diagnostics are more complex and require a series of steps for the user to determine which cause applies. For example, they may need to enter some commands and see what responses return in order to determine the issue. In this case, they are using a <remedy> section with steps to describe this process.

In either case, symptoms are gathered and then a cause is determined, with a link to the appropriate <troubleSolution> pair. So in a tabular presentation, column 1 would be the observable symptoms and column 2 an identification of the cause and a link to the corresponding <cause> (if more information should be provided about the cause) or directly to the appropriate <remedy>. In a step-by-step situation, the <stepresult> potentially identifies the cause and does the linking, or if the cause is still not apparent after that step, the user continues to the next step.

Because of the two distinct ways writers may approach the section, the new <diagnostics> section, specialized from <section> should, like <remedy> allow <steps>, <steps-unordered>, and <steps-informal>. However, it seems awkward to require <steps-informal> if the best way to present the diagnostics is a <table>, so it would be nice to have the model also allow <table> directly as well.

Can we schedule a discussion of this issue to determine if it has merit to move on to Stage 2? Unfortunately, I still have one more class that overlaps the TC meeting on the 12th, but will be at the 19th session.





Attachment: TS_scenarios_DITA_01a[10].png
Description: TS_scenarios_DITA_01a[10].png

Attachment: TS_scenarios_DITA_01b[10].png
Description: TS_scenarios_DITA_01b[10].png

Attachment: TS_scenarios_DITA_02[10].png
Description: TS_scenarios_DITA_02[10].png

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