Introduction
The instruction below is typical of the rules our TextEngineer writers apply every day in their writing and editorial reviews. We incorporate similar material in the corporate style guides we author. In producing a new guide for a client, we first seek information about specialized stylistic needs from management and senior staff in corporate/identity communications, marketing, and engineering. Every writer’s guide – as with every writing coaching program – is crafted to serve the client’s unique needs.
The purpose of the writer’s guide is to impart a higher level of quality and consistency to finished documents, and enable faster review and processing. Following the guidelines we create for you will improve written communications at every level and help promote a standardized “look and feel” in customer documents.
These days, test reports, design specs, and other technical documents represent a critical customer interface. The guidelines developed in your TE writer’s guide will target specific aspects of document authoring and production in a way that will yield noticeable improvements in consistency and presentation quality. In doing so, the guide will become an important component of your firm’s quality culture and testament to an organization that puts customers first.
Sample topics presented here include:
- Technology Communications – General Authoring Principles
- Formal, not Conversational English
- Customer Sensitivity
- Active versus Passive Voice
- Avoid Pathetic Fallacy
- Verb Tenses
- That vs. Which and other Common Errors?
Technology Communications – General Authoring Principles
Why Do We Need Writing Standards?
- They promote the most effective communication outside your organization and with customers.
- Clear, economical, focused writing holds attention. Visually clean, mechanically sound documents minimize editorial complaints and correlate your brand with quality.
- Consistency and uniformity in publications build company identity, enhancing customer recognition and appreciation.
- They embody a proactive rather than responsive stance – set and meet high document standards and prevent customer issues – put the customer first.
What do Standards Govern?
- Page elements – layout, fonts, spacing, graphics.
- English mechanics – spelling, punctuation, grammar, usage.
- Organization and logic.
- Stylistic elements – word choice, writing conventions, sentence length, sentence structure, headings, lists, and so on.
Economy and Impact in Writing
Strive to write simply and clearly. Focus on the purpose of the document and the subject of each section.
The most effective technical writing is taut, information-rich material that easily conveys the most important points. Less is sometimes more. Although we deal with many complex concepts and brevity of expression is a real challenge, we can at least aim for crisp sentences that are free of ambiguity and “fog.” Do not use $50 words when 50-cent ones work as well. Five-line sentences and half-page paragraphs intimidate the reader. Break paragraphs logically by discrete thoughts.
Evaluate your own drafts to identify tangential material and unnecessary verbiage that can be eliminated. The goal is sharply honed text and high-quality, relevant graphics that facilitate rapid reading and full comprehension.
Avoid wordiness and words or phrases that obscure the central meaning, for example:
Wrong: The system is designed such that active components are capable of being tested during plant operation.
Right: The active components can be tested during plant operation.
In summation, you should adopt a spare, direct business writing style that eliminates stilted, circuitous language. Avoid using “proposalese” and similar interest-draining patterns at all times.
Formal English
Technical information requires more stringent standardization than is common in general usage. Colloquialisms and conversational English are inappropriate for business and technical writing. Keep language precise; formal without sounding pedantic.
Customer Sensitivity
Condescension Harms Your Message
Do not talk down to reviewers and customers. Examples:
It is evident that…
One must conclude that…
Obviously…
Use Customer Terminology
Know and use customer titles for their programs. When a customer has a preferred name for an item or system that differs from the company’s term but is equivalent, favor the customer’s term.
Active versus Passive Voice
Proposals and Marketing Documents
Traditionally at engineering firms, proposal managers and marketing staff have advocated assertive language and active voice to raise impact. Examples:
Passive: After installation of the new equipment, production was doubled.
Active: After installing the new equipment, the team doubled production.
Passive: Several laboratory tests were conducted on the specimens.
Active: The laboratory conducted several tests on the specimens.
Technical Documents
In technical reports, calculations and specs, it is often considered appropriate to “mask the subject” (i.e., avoid references to I, we, the designer, or the analyst) and use passive voice. This has the effect of shifting emphasis from the performer of action (design, analysis, establishment of requirements) to the analysis results, conclusions, or requirements themselves. In other words, it gives the object in the sentence dominance over the subject.
Example 1: The IEEE requirements must be met by all vendors.
Example 2: From the simplified analysis model of [1], the following structural parameters were calculated for the steel supporting beams.
Even in strictly technical documents, however, you can apply active voice in discussions not directly connected to the main analytical or engineering content to break the detached quality of passive voice and raise interest.
Avoid Pathetic Fallacy
Steel has No Soul
“Pathetic fallacy” means the attribution of human qualities to inanimate objects. Be on guard for it, and know that lifeless components and sensors cannot “see” or “experience” anything, though they may be subjected to, or exposed to, a range of conditions.
Similarly, a management plan cannot ensure and a site cannot consider. Only humans can do these things.
Possessive
A point related to pathetic fallacy is to avoid using the possessive with anything other than persons or entities.
Wrong: The project’s expenditures …
Right: The project expenditures …
Verb Tenses
What’s the Right Tense?
While present tense is usually correct in technical writing, there are notable exceptions. Use future tense when describing activities that the company or a customer has yet to perform. Use past tense when discussing completed activities, or actions done during analyses or inspections.
Will versus Shall
Use “shall” only when discussing legal/contractual issues, design or functional requirements, or acceptance criteria. Use “will” in every other application of future tense.
Conditional
Conditional (the present subjunctive mood) can describe a hypothetical situation, for instance:
If the MOV failed to close under these conditions, the consequences would include …
Tenses Not Used
In technical documents, past perfect and future perfect tenses should generally be avoided. To illustrate, you should only rarely need to use constructions like:
- An analysis of the bisulfate compound had shown … (past perfect – delete “had”)
- The maximum damping will have been applied in a future study. (future perfect – change to will be used)
There are occasionally valid applications for the present participial and past perfect forms, typically in sections providing background information, for example:
- The team is performing this study in conjunction with the module replacement. (present participle)
- The lab has used this testing methodology since 1995. (past perfect)
That vs. Which and Other Common Errors
- The word “comprise” means to include or to be made up of. A large entity cannot be comprised of smaller things. It comprises them, or is composed of them.
- That/which – the relative pronoun that is restrictive, which means it tells you a necessary bit of information about its antecedent, e.g., The alloy that is used most often is INCONEL. Which is nonrestrictive, meaning it does not limit the word it refers to. Simple rule: if you can tell which thing is being discussed without the which or that clause, use which; if you cannot, use that. If the phrase needs a comma, you probably want which.
- Data, criteria, and spectra are all treated as plural nouns. Other common plural forms: moduli (not modulii or moduluses), formulae (preferred over formulas).
- Principal means main or primary; principle is a motivating idea.
- Affect is a verb meaning “to have an influence on,” while effect is the result of being affected.
- Basically is much overused and should be avoided in favor of such expressions as essentially or fundamentally.
- The phrase close proximity is a redundancy, since in proximity to means close to.
- e.g./i.e. – When you mean “for example,” use e.g. – an abbreviation for the Latin phrase exempli gratia. When you mean “that is,” use i.e. – an abbreviation for the Latin phrase id est. Both are used to clarify a preceding statement, the first by example, the second by restating the idea more clearly or expanding on it.
- Envelop means to enfold or encompass. Dictionary.com defines envelope as “the set of limitations within which a technological system, especially an aircraft, can perform safely and effectively.” It is either that or what you send to the mail room, but envelope is never a verb.
- LCD display, FEM model, etc. – LCD stands for “liquid crystal display,” so it is redundant to write LCD display. FEM stands for “finite element model,” so do not repeat model. Be careful about this in all acronym usage.
- Title/entitle – a fine point not often observed, but it is preferable to say the document is titled the Configuration Management Plan versus entitled the same. A document is titled; an heiress is entitled.
- Practicable; possible; practical – To quote The Chicago Manual of Style (CMS 5.202): “What is practicable is capable of being done; it’s feasible. What is possible might be capable of happening or being done, but there is some doubt. What is practical is fit for actual use.”
Additional Technical Writing Resources
TextEngineer writers and editors use all the reference sources on our “Writing Resources” page regularly. You may find them quite helpful when wrestling with questions of grammar, style, meaning, or even spelling.
Also see our “Writing Conventions” page.
TextEngineer.net search terms:
- basic principle of effective technical writing
- What are the qualities of the finished technical writing
- what are the basic principle of effective technical writing
- the tense that has to be used while writing User Manuals
- technical writing conventions
- technical writing common patterns of organization-
- shall in technical writing
- pathetic fallacy in the popular mechanincs
- past tense quiz technical writing
- must do as a technical writer
- will vs shall in technical writing
Latest Comments