From: Henry Spencer (henry@spsystems.net)
Date: Wed Jul 07 2004 - 14:44:03 CDT
On Thu, 1 Jul 2004, Bruce Lilly wrote:
> ...Unlike the other documents, the Kohn draft does not
> include example messages -- that can be seen as an advantage for several
> reasons...
It can also be seen as a crippling disadvantage, because it makes the
document far harder to reliably understand. Not only do examples help the
reader come to an understanding of difficult material, but even more
important, they let him *check* his understanding of difficult material.
Yes, they have to be carefully written, and consistency with the text
requires real effort, but they are extremely important for a practical
standard.
Even the ISO standards, which are about as fussy and formal as they come,
to the point of banishing most explanatory material to appendixes or even
separate documents, are often replete with examples when the subject is at
all difficult. Look at the C99 standard as a case in point.
> 1. Examples should probably be placed in an Appendix (see RFCs 2421, 2822,
> and 3464) clearly marked as not indicating normative text and as being
> *only* _examples_.
Marking is good when there is room for doubt, but banishing to appendixes
is not, for the most part. The examples should accompany the text they
refer to, so the two can be read together easily. (Appendixes, or
separate sections, are not unreasonable for larger and more complete
examples, but that's different from short examples illustrating specific
issues.)
Henry Spencer
henry@spsystems.net