Packetizer

Guidelines for Writing Standards

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 and WordSmith Workshop. 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.
Incorrect: The called endpoint includes this data in all messages up to and including the Connect message.
Correct: The called endpoint shall include this data in all messages up to and including the Connect message.

Write in the active and not passive voice.
Incorrect: System capabilities shall be exchanged by transmission of the H.245 terminalCapabilitySet message.
Correct: Endpoints shall exchange system capabilities by transmitting the H.245 terminalCapability message.

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.
Incorrect: A call may be established directly between two endpoints, or may include other H.323 entities such as a Gatekeeper or MC.
Correct: A call may be established directly between two endpoints or may include other H.323 entities such as a Gatekeeper or MC.
Correct: A call may be established directly between two endpoints, or it may include other H.323 entities such as a Gatekeeper or MC.

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.
Incorrect: Only the Gatekeeper shall close the Call Signalling Channel and it should not be closed when a Gateway is involved in the call.
Correct: Only the Gatekeeper shall close the Call Signalling Channel; it should not be closed when a Gateway is involved in the call.
Correct: Only the Gatekeeper shall close the Call Signalling Channel, and it should not be closed when a Gateway is involved in the call.

In a list of three or more elements, all elements except the last one are followed by a comma.
Incorrect: The protocolIdentifier is included as part of discovery, registration and Setup/Connect...
Correct: The protocolIdentifier is included as part of discovery, registration, and Setup/Connect...

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.
Incorrect: call setup message
Correct: call-setup message

Incorrect: Gatekeeper based user location
Correct: Gatekeeper-based user location

Incorrect: enhancement level three
Correct: enhancement-level three

Incorrect: transport level resource reservation mechanisms
Correct: transport-level resource-reservation mechanisms

Conversely, the following phrases don't need hyphens because the default association rules are what was intended.
Correct: network byte order
Correct: base video session

Use diagrams, such as SDL or state diagrams, whenever possible because they tend to be more succinct and less ambiguous than prose.
Incorrect: While in state A, event X causes a transition to state B.
Correct: ( A )-X--->( B )

If a component in a data structure is optional, describe what the absence of the value means.
Incorrect: rsCodeCapability BOOLEAN OPTIONAL
Correct: rsCodeCapability BOOLEAN OPTIONAL -- EP shall assume FALSE if absent

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

  • zero components (empty)
  • exactly one component
  • more than one component
  • component order