Writing Specifications

  1. The need for clarity
  2. Sentence structure
  3. How grammatical errors in specifications are handled
  4. References
  5. Elegant Variation
  6. Types of ambiguities
  7. Totality
  8. The slash mark "/"
  9. Verb tenses and auxiliary verb usage
  10. Requirements on individuals vice the equipment
  11. Point-of-view for reviewers of specifications
  12. Modifiers that apply to two or more nounsv
  13. Essential and nonessential dependent clauses
  14. Multiple conjunctions
  15. Specifications in the third person
  16. Lists

Quick Grammar Review


The need for clarity

Puzzeled

The most obvious reason for writing clear specifications is to ensure that you will inform the contractors' engineers well enough that they can actually produce the product you need.  However, there is another reason why the specifications and statements of work for public contracts must be clear:  fairness to all offerors.

If one offeror happens to have better access to inside information about the work to be done than the others, then vaguely written specifications will give that offeror an unfair advantage over competitors who may be perfectly capable of doing the work, but lack knowledge about some of the details.  The protest that may result from such a situation will take a great deal more time and effort to resolve than you would have to spend sharpening up a vaguely worded document.

Sentence structure

Keep your sentences short and simple. It doesn't matter if specifications read like a grade-school textbook. We're not trying for a Pulitzer Prize.

Many times, I have found sentences so long and complex that the writer became confused, and ended up saying something different from what was intended, or maybe nothing at all .

I once was asked to examine the specifications for a job where the contractor had submitted a claim. Only one sentence in that lengthy document described the essential function of the equipment. That sentence was so long and complex that its author couldn't see some of his errors in grammar. The errors made the sentence unenforceable. In that situation it was impractical to do much other than pay the contractor's claim, accept the equipment as-built, even though it didn't work right, and fix it ourselves.

Here's an editing trick that will help you write clearer sentences: When you've written a sentence, read it back to yourself with all the modifiers and subordinate clauses deleted. Read only a short subject, the main verb, and a short object. You'll be surprised at how many long sentences boil down to nonsense.

How grammatical errors in specifications are handled

There are three categories of grammatical errors.

  1. Those that don't affect the intelligibility of the sentence. An example would be "Joe ate less doughnuts than John." It should read "fewer doughnuts," but no one can argue about what the writer intended.
  2. Those that make the sentence totally unintelligible. These don't often get past the review cycle, but when they do, the contractor may legitimately ignore them in designing and building the equipment. Usually we're lucky and the contractor tells us about them, and we fix them with an ECP .
  3. Those that leave the sentence somewhat intelligible, but change the meaning of the sentence to something different from what was intended. For example, see the article on restrictive and non-restrictive clauses.  In this case, even a contractor who has a policy of goodwill towards the Government is likely to build equipment to meet the erroneous requirement. Eventually, the error will be discovered, and will be fixed by either an ECP or a modification. The result is cost growth .

References

Four articles discuss different types of references.

  1. References to other documents in the procurement package
  2. Cross references to other paragraphs
  3. References to specifications and standards
  4. Usage of acronyms

Elegant variation

You probably have been taught for aesthetic reasons to avoid repeating the same words and phrases. For specification writers, such practice may be disastrous. Forget what your teacher told you; you're not competing for a Pulitzer prize. It is extremely important for clarity, that you refer to things using exactly the same words every time.

Some good examples of synonymous (or nearly so) terms often erroneously used together in training device specifications are:

If you intend to distinguish between the meanings of terms like these, you must define each term in the document. If you intend no difference in the meaning of two words, use only one of them.

Types of ambiguities

Ambiguous sentences can be interpreted to have more than one meaning. Three types of ambiguities are found in sentences. These are:

  1. Ambiguous words,
  2. Syntactic ambiguities, and
  3. Contextual Ambiguities.

Ellipsis is another related phenomenon of language mentioned in this context because the notion is similar.

None of these phenomena is acceptable in engineering specifications. You should be aware that some contractors employ skilled analysts whose job is to find ways to interpret your words differently from what you intended. These interpretations may be used as the basis for reducing requirements and for the submission of ECPs and claims. The practice is known in the business as "finding money in the contract."

Totality

Totality is an idea that is easily expressed in words, but very rarely occurs in real life.  We use it whether we really mean it or not. When you use words like: "all," "always," "never," "every," and "none," you may be creating a logical error.  Conflicting requirements often result from totality statements when something else in another sentence makes an exception to the totality.

Now that you're aware of the totality problem in language, here's a trick you can play on your friends and co-workers:  Listen for them to use the phrase "all the time" in conversation.  When they do, take the statement literally and comment on its illogic.  For example:

caricature of Mary

Mary: "I go to the public library all the time."

You:   "Mary, if you were at the library all the time, then you wouldn't be here in the office right now."

Needless to say, your friends will be impressed with the preciseness of your reasoning.  After doing this awhile, just a snicker will suffice.  Soon you'll find that you have enriched their vocabularies with uncommon words like "often," "usually," and "sometimes."

The slash mark "/"

See also "and/or".

Properly called a "virgule," the slash mark is often found in draft engineering specifications. The purpose of this article is to convince you to never use one in a specification.  In fact, it's not even good form in ordinary writing.

The dictionary says about the virgule: "an oblique stroke (/) used between two words to show that the appropriate one may be chosen to complete the sense of the text." Please note that it's your contractor who gets to decide which word is proper. Note also that the dictionary tells the contractor to choose just one, not both.

When we write A/B, we usually mean "either A or B" or "either A or B or both" or "both A and B" or "number of A's divided by number of B's." There's no telling which one.

In many cases, substituting a hyphen for the slash will fix the problem. For example, we see "instructor/operator" in training device specifications where "instructor-operator" would be more clear.

In most cases you'll have to write "A or B or both," or whatever you really meant.

Verb tenses and auxiliary verb usage

When writing specifications we always state requirements in the future tense using the emphatic form "shall." Hence, the finished product SHALL be, SHALL produce, SHALL consume... Government policy on this is stated in MIL-STD-961E. The weaker auxiliary verbs "will," "should" and "may" do not express a requirement. In the case of "will," the sentence places responsibility on the purchaser. "May" grants permission, and "should" states a preference.  "Must" is ambiguous, since it may express a presumption instead of a requirement.  For example:

John must love Deborah; after all, they've been happily married for over twenty years.

Correct usage of "shall" and "will" in specifications is extremely important, and is a frequent source of errors found in drafts.

A large number of people think that only sentences containing the word shall can express requirements, and their belief is reinforced by an ANSI/IEEE standard, 830-1984. Some contractors are even using software based on that standard to decompose specifications into a databases of individual requirements. Hence, if your requirement does not contain the word "shall," it will not become an entry in the resulting database of requirements.

Requirements on individuals

The goal in writing engineering specifications is to specify the performance or design of a product. Specifiers should confine themselves to just that. "The operator shall be capable of . . ." does not require that the equipment do anything. It only requires that the operator have an ability.

In the case of engineering specifications, it is not likely that this is what the writer meant to say. More likely the writer meant "The equipment shall . . , under control by the operator."

Statements of Work are different. In a SOW, you may specify the skills, abilities and other qualifications that people must have to do the work specified.

Point-of-view for reviewers of specifications

Catching subtle errors is hard for most specification writers because they read the drafts from their own point of view. This statement may sound like nonsense, but it's not. The idea here is to introduce you to what is known to professional writers as "audience analysis."

Most engineers presume that the audience for their specifications consists only of other engineers with whom they share similar experience and objectives. Such a view is seriously mistaken, since the audience for specifications includes a very large number of non-engineers as well. Some of those non-engineers may even be lawyers and judges.

In the case of specifications, a useful form of audience analysis can be applied by role playing. Shift your mental gears into reverse and look at the words you've written as if you were a business owner in dire financial straits. Think as if you've run out of money and are looking for ways to deliver less than what was planned, but still stay within the letter of the contract. If you can't find ways to cut costs on this job, you're going to default on a big loan and be forced into bankruptcy. Everything you own is tied up in the business, and you stand to lose it all because you've underbid. Your objective is to satisfy the letter of contract without satisfying the customer. You know that your customer will think you're a chiseler for delivering less than what was expected, but in this situation a satisfied customer is a luxury you simply can't afford.

By the way, the act of shifting mental gears as described above is known to people who study critical thinking as "recontextualizing," and is the basis for a whole philosophy known as deconstructionism.

Modifiers that apply to two or more nouns


Dog and Cat

We often get confused when a writer tries to apply a modifier to two or more nouns without writing the modifier twice.

Here's an example:

The flange shall be fastened by nuts and bolts of stainless steel.

Which is stainless, both the nuts and the bolts, or just the bolts?

If you get into a dispute over specification requirements that have this kind of an ambiguity, it will probably be settled by applying the modifier only to the noun that appears nearest to the modifier. Unless the context indicates otherwise, cases of confusion like this one are usually resolved by attaching the modifier only to the nearest word that it may modify. Lawyers call this approach to resolving ambiguities "the doctrine of the last antecedent." It is a rule that is easy to run afoul of, especially when the sentence in question is long and complicated.

Essential and nonessential dependent clauses

See also:  restrictive and nonrestrictive

The ability to distinguish between essential and nonessential dependent clauses is an extremely important skill for specification writers. When a clause that was intended to be essential is inadvertently written as nonessential, or vice versa, the requirement stated by it may be distorted or lost. The visible difference between the two is nothing more than a comma before the introductory word. The nonessential clause gets the comma. Here is a list of introductory words and phrases that may introduce both essential and nonessential clauses, and therefore require the utmost caution:

after
as
as if
as though
as soon as
at which
because
before
by which
for which
if
in order that
since
so that
to which
unless
when
where
which
while
who
whom
whose

Multiple conjunctions

When you write sentences with two or more conjunctions, you risk producing an ambiguity. For example,

The flange shall be fastened by gluing and clamping or riveting.

could mean "gluing and clamping or riveting" or it could mean "gluing and clamping or riveting," with the bold characters added for clarity. Unfortunately, English does not provide us with a means of declaring the order of application of its logical operators the way computer languages do. The burden of resolving the confusion of precedence is placed on the writer, who must find a different way of expressing the idea without ambiguity. In the above case try

"The flange shall be fastened either by gluing and clamping or by riveting."

Specifications in the third person

Normally we write specifications so that they always refer to the third person. Forcing your writing into the third person is difficult, and often makes the sentences difficult to read. It runs contrary to the advice of modern writing teachers who are trying to reform us, and is also contrary to the advice of the Construction Specifications Institute. BUT, the rest of the world is expecting to see specifications written in the third person, and writing them otherwise is inviting criticism. Hence, using the words "I," "we" and "you" is frowned upon.

If you MUST refer to the first or second person, be sure you define the meaning of the pronouns, and use them only as defined.

Lists

Whenever you compose a list in the text of your specifications, you should take pains to make it complete and easy to read, and that its elements all consist of parallel parts of speech.

Completeness of lists

Take the time to think of everything you could possibly want to include in your list.  Generally speaking, the best policy for specification writers to follow is "If you don't mention a thing explicitly, then don't expect to get it."  Adding generalized list elements, like "and others," "and the like," or the words "not limited to" will probably not get you something you haven't mentioned explicitly.  Generalized list elements add little meaning to the text, and can often be ignored by readers.  If you must use generalized terms, then use them alone and unaccompanied by specific items.  By mentioning one thing explicitly, you may be excluding others.  So often and for so many years has this method of interpretation been used that lawyers have a Latin name for it:  "Expressio unis est exclusio alterius," which means "to say one thing is to exclude the other."  Sometimes generalized list elements are subject to interpretation according to another legal canon known as "ejusdem generis," which limits the unwritten elements to members of the same family.  For example, the list "resistors, capacitors, inductors and other components" could be interpreted as not applying to transistors, since transistors are active components and all the listed components are passive.

Readability of lists

When the elements of a list become numerous, the visual clutter of the text makes it difficult to read, and readers are therefore likely to miss one or more of the elements.  This human-factors problem is easily solved by listing the elements vertically with bullets or subparagraph labels and separated by blank lines.  For example:

    Temperature-rise specifications shall apply to
  1. resistors,
  2. capacitors,
  3. inductors, and
  4. transistors.

As a rule, indented lists are always preferred in technical documentation.

Parallelism in lists

The elements of each list should all be the same part of speech.  For example, the list:

  1. safety,
  2. rowboats,
  3. resuscitate, and
  4. life preservers

is incorrect because "resuscitate" is a verb and all the other three elements are nouns.  This list's elements should have been all nouns.

NAWCTSD NAVAL AIR WARFARE CENTER
TRAINING SYSTEM DIVISION
ORLANDO FLORIDA


NAWCTSD Navigation Text Version
Last Update: 7 May 2013