Packetizer Logo
 

Guidelines for Writing Standards

Author: Paul Long, ~2001

Good grammar and clear writing reduce ambiguity and make standards easier to read. This results in greater interoperability between disparate products which in turn increases and hastens market acceptance, sales, revenue, and ultimately profits. There are several good web sites for writing, including Online Writing Lab at Purdue University. The following are topics to which writers of standards, including editors and contributors, need to pay special attention. These guidelines assume the English grammar used in North America. Our apologies to speakers of other English dialects, especially those who speak "true" English. :-)

Use the normative verbs prescribed by the sanctioning standards body. Other declaratory verbs do not have force in a standard and are therefore merely editorial. For example, in an ITU Recommendation, only "shall," "should," and "may" are prescribed.

Write in the active and not passive voice.

Don't put a comma between verb phrases in a compound predicate. This is where a verb phrase "borrows" the subject from the preceding verb phrase.

There are only a couple of ways to combine two independent clauses into a compound sentence. Link them with either a semicolon by itself or a coordinating conjunction (and, but, for, or, nor, so, yet) followed by a comma.

In a list of three or more elements, all elements except the last one are followed by a comma.

In English, individual adjectives within a compound adjective preceding a noun associate from right to left. If this is not your intent, use the hyphen to bind adjectives.

Conversely, the following phrases don't need hyphens because the default association rules are what was intended.

Use diagrams, such as SDL or state diagrams, whenever possible because they tend to be more succinct and less ambiguous than prose.

If a component in a data structure is optional, describe what the absence of the value means.

For a component list, always describe the semantics of the following situations even if it is obvious to you, the writer.