TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
Subject:Re: Re: Comma, comma, coma[,] and Uncle Ralph From:Loren Castro <LFC -at- SOL -dot- BITNET> Date:Sat, 13 May 1995 15:04:02 -0700
We suffered a major simultaneous software and hardware upgrade Friday, and my
first attempt to respond to Joyce's post bounced. This is the second attempt.
If it looks familiar, it is. If it looks slightly different, it is.
Joyce apparently misunderstood me and wrote the following:
> snip, snip, snip
> Part of my job is to review a contractor's software documents for
> those qualities and for compliance with DOD standards. (I'm talking
> about the big defense contractors here, not you independents.)
So there! You independent peons you!--you who have about as much
respect for a standard as a tomcat has for a marriage license!
In milspec language, "consider yourself told!" j
> I want to see "shall" used consistently for provisions that are
> contractually binding.
Personally, I have been on a one-person crusade to eliminate
"shall" from technical documentation. Does it mean 1) likely
to happen in the future, or 2) mandatory? j
I intended no slam at the independents. In fact, I was trying to distinguish
them from the big defense contractors, who routinely write substandard
specs. My experience with the defense contractors is that they make their
really talented software engineers write the documentation--with predictable
results. I have re-read my statement, and I just see no insult in it.
Please believe that I meant none.
Yes, "shall" is ugly because we don't use it much in our idiom. But like it
or not, it is necessary in government specs for three reasons: (1) It is
grammatically correct. Look up "will" and "shall" for the second and third
persons. (2) It identifies the provisions that are (as I understand it)
legally and contractually binding. (3) It identifies, for example, the
software requirements that must be testable. If the statement doesn't say
"shall," the requirement doesn't get tested.