markups

[Syed.Hosain at aeris.net]

> I have an OT questions -- when you mark up someone's document, or when
> they mark up your document, how do you determine between "must change"
> markups and "strongly recommend" markups?

We require the reviewers to be clear in what they want! :)

Separate, but related, all our technical documentation and specs contain
the following paragraph near the beginning:

	Key Words

	The key words "must", "must not", "required", "shall", "shall
not", "should", "should not", "recommended", "may", and "optional" in
this document are to be interpreted as described in 'Aeris Key Words to
Indicate Requirement Levels'.

And the "Aeris..." document above - as well as these words used in the
specs - is heavily based on RFC 2119 (available here:
http://www.ietf.org/rfc/rfc2119.txt?number=2119). I.e., we follow the
RFC guidelines cleanly.

Then, people doing the document reviews internally here - before release
- have learned to mark their comments accordingly. The use of the word
"must" and "should" are particularly important - people often use
"should" when they mean "must"!

Marketing docs and collateral do not contain the words mentioned above,
of course, but our reviewers know to mark them the same way. :)

Z