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: 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.





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