Fwd: Troubleshooting topic

[JoAnn Hackos <joann.hackos@comtech-serv.com>]

From Bob

Sent from my iPad

JoAnn Hackos

Comtech Services Inc

Begin forwarded message:

From: Bob Thomas <bob.thomas@tagsmiths.com>
Date: July 22, 2012 1:45:03 PM MDT
To: Joann Hackos <joann.hackos@comtech-serv.com>
Subject: Troubleshooting topic

Hi JoAnn,

I attempted to post this to the list, but I don't have sufficient permissions. Would you please send this out?

Bob

Hello,

Today I unenthusiastically began to implement a new version of the troubleshooting strawman. While mulling over what to do, I came up with an alternative that we ought to consider.

Current situation
The fact that steps are locked inside of task severely limits our ability to create a simple troubleshooting topic that can re-use steps from existing tasks. The initial strawman achieved that goal, but it violated DITA architecture, so it had to be abandonned. The current idea is to remove the steps element from the remedy element to stay within the bounds of DITA architecture, and then to reintroduce steps by allowing the troubleshooting topic to become a composite topic type with embedded tasks providing a mechanism to re-use steps.

This solution loses the semantics of successive condition -> cause -> remedy fallbacks that were available in the original strawman. Furthermore, it introduces some task-related semantics that are generally not useful in a troubleshooting scenario. If we presume that most adopters are using the strict taskbody constraint, then there is no good place to discuss cause and condition for each fallback situation (assuming multiple embedded tasks).

An alternative to consider
We could perform some DTD gymnastics to do the following:

1. Abandon the current strawman, and specialize off of task
2. Create three domain specializations of prereq called cause, condition, and remedy.
3. Modify the strictTaskbody constraint to use prereq instead of the %prereq; parameter entity in the constraint's taskbody content model. In the off-chance that somebody else has also chosen to implement domain specializations for prereq, they would have to replace the strictTaskbody constraint with one of their own that would allow their specialized elements.
4.  In the troubleshooting body element, exclude prereq, context, and section from the possible preceding siblings for steps. This would leave only cause, condition, and remedy.
5. Create a usage guideline saying that fallback scenarios would be implemented such that all steps are contained within sibling embedded troubleshooting topics. This means that, for fallback troubleshooting, the steps element in the outer troubleshooting topic would not be used.
   

This is still icky, but it is somewhat better than what I had set out to do today with embedded tasks.

Regards,

--
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)