Re: [dita-techcomm] A spot of bother in the content model for troubleshooting

[Bob Thomas <bob.thomas@tagsmiths.com>]

Hi JoAnn,

I failed to consider the case for complex troubleshooting when I agreed to removing title. Partly, because I was euphoric over getting rid of the requirement to be backward-compatible with the IBM troubleshooting specialization.

I am now questioning the wisdom of omitting <title> from <condition>, given that there won't be generated titles for <cause> or <remedy>. You could also make the case that allowing <title> in <condition> would make troubleshooting easier to use for related remedial information such alarms, events, and errors. For example:

<troubleshooting>

  <title>ALM934</title>

  <troublebody>

    <condition>

      <title>Severity</title>

      <p>Minor</p>

    </condition>

    <cause>

    ...

    <remedy>

    ...

  </troublebody>

</troubleshooting>

Therefore, the <condition>, <cause>, and <remedy> elements ought to allow <title> at their beginning. I would like for the titles to be optional so that implementers could use constraints to remove them from the content models. That would allow a stylesheet-generated labels implementation to be created. 

There are no inheritance issues with this change. <condition>, <cause>, and <remedy> would still inherit from section.

Best Regards,

Bob Thomas

On Tue, Oct 22, 2013 at 1:24 PM, JoAnn Hackos <joann.hackos@comtech-serv.com> wrote:

I agree completely. We should be able to make that change for the Stage 3 proposal. I know we discussed it and I was positive about including Title.  Do you have to change the inheritance model for this to work?

JoAnn

Sent from my iPad

JoAnn Hackos

Comtech Services Inc

710 Kipling Street Suite 400

Lakewood CO 80215

 

CIDM will be hosting the Content Management Strategies/DITA Europe Conference 2013 in Munich, Germany November 18-19. More information at:

http://www.infomanagementcenter.com/DITAeurope/2013/index.htm

On Oct 22, 2013, at 1:17 PM, "Bob Thomas" <bob.thomas@tagsmiths.com> wrote:

Hi,

While working on a feature article for the DITA Adoption SC that discusses troubleshooting for DITA 1.3, I have come across a deficiency in the content model for the <cause> and the <remedy> elements. I now believe that <cause> and <remedy> ought to allow an optional <title> element at their beginning rather than relying upon static, stylesheet-supplied strings for labeling.

The stylesheet-supplied, string method is sufficient for troubleshooting topics that contain a single cause-remedy pair (simple troubleshooting topics). But, in topics that contain two or more cause-remedy pairs (complex troubleshooting topics), the author is left with no good way to distinguish them from each other through labeling. At a minimum, the titles for the causes need to signal the essence of each cause.

You can make a case a title is also needed for remedy in complex troubleshooting topics, whenever remedy appears without an associated cause. For example, a common final fallback would be a stand-alone remedy such as this:

<remedy>

  <title>Contact technical support</title>

  <steps-unordered>

    <step><cmd>Contact technical support at either support@foo.com or 800-555-1234</cmd></step>

  </steps-unordered>

</remedy>

I am sorry to raise this objection at this point. However, I don't think that the current model fully supports complex troubleshooting information without this change.

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

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