How much "context" to show in examples?

We talked a bit about this at last week’s TC meeting, and Robert and I talked about this at our spec editors’ meeting yesterday and made decisions.

The question (raised by Tammy Crowley) concerned the following code sample for <troubleSolution>, and the question was whether it would be better shown in the context of the <troublebody> element:

Original code sample

<troubleSolution>

<cause>The <msgnum>E247</msgnum> error message is generated due to a

transient memory fault.</cause>

<steps>

<step><cmd>Reset the alarm.</cmd></step>

<step><cmd>Monitor the system periodically to see whether the alarm recurs.</cmd></step>

</steps>

</remedy>

</troubleSolution>

Robert and I agree that the following would be better:

<title>E247: Memory fault has occurred</title>

<troubleSolution>

<cause>The <msgnum>E247</msgnum> error message is generated due to a

transient memory fault.</cause>

<steps>

<step><cmd>Reset the alarm.</cmd></step>

<step><cmd>Monitor the system periodically to see whether the alarm recurs.</cmd></step>

</steps>

</remedy>

</troubleSolution>

</troublebody>

</troubleshooting>

Note that this is a pattern ONLY for elements that are components of structural specializations, not base constructions or domain elements. Also, the following considerations apply:

Snip the code as necessary to make the code sample not otherwhelmingly long
Scrap this pattern if following it makes the code sample too involved or ;ong.

Best,

Kris

Kristen James Eberlein
Chair, OASIS DITA Technical Committee
Owner, Eberlein Consulting LLC
kris@eberleinconsulting.com

Skype: kriseberlein; voice: +1 (919) 622-1501

dita message