From "Writing as an Engineer" by David Beer and David McMurrey
a.) When they bought the machine they weren’t aware of it’s shortcoming.
b.) There was not a sufficient enough number of samples to
validate the data.
c.) Our intention is to implement the verification of the
reliability of the system in the near future.
a.)
The possessive form of it = its
it's = it is
it's = it is
Example:
It's raining today. (It is raining
today)
The dog wagged its tail.
b.)
redundant and wordy:
There weren’t enough samples to
validate the data.
c.) Wordy
We want to verify the system’s
reliability soon.
Focus on:
- Why you are writing.
- Why you are writing.
- to inform, request, instruct, propose, recommend, persuade, record?
- Who are your readers?
- Fellow engineers from your field?
- Engineers from a different field?
- Managers? Marketing?
- Mixed audience?
Are you communicating technical information on a level your
audience can use?
Are you using
appropriate vocabulary, examples, definitions, and depth of detail?
Satisfy Document Specifications
Satisfy Document Specifications
- Adhere to suggested length.
- Format spec’s: headings, spacing, margin widths, font
- Format spec’s: headings, spacing, margin widths, font
Get to the Point
- Put important info first.
- Intro - briefly state key points, complaints, requests, and conclusions.
- Do not include details until the body of the text.
Accuracy
- Accurate references
- Accurate directions and instructions
- clearly state the conditions your data is applicable to.
- Do not state opinions as facts.
Logical Presentation
and organization:
- Numbered sections and subsections with titles.
- Organize in levels of detail and importance
- main subject first
- fill in the details later
- First level headings should be in large font
- separate headings from text by one line
- indent minor headings
Use Lists
Lists are often the most efficient way to communicate information.
List material from most important to least important
3 types of lists:
- numbered (or lettered) for procedures, or prioritized lists
- checklists – for things you need to do
- bullet lists – items in list occur in no specific order
Be Clear & to the
point:
Ambiguity – comes from the Latin
word meaning to be undecided, causes readers to see more than one meaning in
your writing without knowing which is correct.
Avoid words like “they” and “it” to be specific and avoid ambiguity.
Ex:
Ambiguous: Before accepting materials from the new subcontractors, we should make sure they meet our requirements.
Who are “they”? the materials? Or the contractors? or both?
Clear: We should make sure the materials from the new subcontractors meet our requirements before we accept them.
Ambiguous: The microprocessor interfaced directly with the 7055 RAM chip. It runs at 5 MHz. (What does “it” refer to?)
Clear: The microprocessor interfaced directly with the 7055 RAM chip. The 7055 runs at 5 MHz.
Vague – contains no useful information.
Example:
“Take a few of these pills every so often.” How many pills? How often?
Vague: The Robotics group is several weeks behind schedule.
Useful: The Robotics group is six weeks behind schedule.
Vague: The CF553 runs faster than the RG562 but is much more expensive.
Avoid words like “they” and “it” to be specific and avoid ambiguity.
Ex:
Ambiguous: Before accepting materials from the new subcontractors, we should make sure they meet our requirements.
Who are “they”? the materials? Or the contractors? or both?
Clear: We should make sure the materials from the new subcontractors meet our requirements before we accept them.
Ambiguous: The microprocessor interfaced directly with the 7055 RAM chip. It runs at 5 MHz. (What does “it” refer to?)
Clear: The microprocessor interfaced directly with the 7055 RAM chip. The 7055 runs at 5 MHz.
Vague – contains no useful information.
Example:
“Take a few of these pills every so often.” How many pills? How often?
Vague: The Robotics group is several weeks behind schedule.
Useful: The Robotics group is six weeks behind schedule.
Vague: The CF553 runs faster than the RG562 but is much more expensive.
Useful: The CF553 runs 84% faster than the RG562 but
costs $4,320 - $2,840 more than the CF553.
Coherence – comes from the word “cohere” or stick together.
Clear transitions – use words like “because”, “this shows”, “in addition”, “thus” to link sentences to one another.
Coherence – comes from the word “cohere” or stick together.
Clear transitions – use words like “because”, “this shows”, “in addition”, “thus” to link sentences to one another.
Use a clear subject for each paragraph
Everything should support the subject of report
Directness:
Avoid suspense.
Put the most important information first.
example: Indirect: After a long and difficult development cycle due to factory renovation, the infrared controller will be ready for production in the very near future.
Direct: The infrared controller will be ready for production March 4. Its development cycle was slowed by the factory renovation.
Avoid wordiness
Avoid unnecessarily pompous or ostentatious & showy words. The point of technical documents is to convey information, not to make yourself look smart.
keep it simple and straightforward.
Remember, often your readers have English as their second language.
pompous - straightforward
Commence – start
Compel – force
Comprises – is
Employ – use
Endeavor – try
Fabricate – make
Finalize – end
Initiate – begin
Optimal – best
Prioritize – rank
Proceed – go
Wordy: I regret to say that at this point in time I
basically do not have access to that specific information…
Clear: “I
don’t know.”
Wordy – efficient
A large number of – many
At this point in time – now
Come in contact with – contact
Exhibits the ability to – can
In the event of – if
In some cases – sometimes
In the majority of instances – usually
Redundancy
using multiple words to say the same thing
Redundant – clear
using multiple words to say the same thing
Redundant – clear
Alternative choices – alternatives
Actual experience – experience
Completely eliminate – eliminate
Connected together – connected
Collaborate together – collaborate
Very best – best
Component part – just say either “component” or “part”not both
Turning verbs into nouns:
Write in an active voice (rather than passive) by using verbs instead of nouns.
wordy – clear
An analysis of the data – analyze
An investigation of xyz – xyz was investigated.
made a selection – select
made a selection – select
Procurement of services can be accomplished by – services
can be procured by
Paragraph Length:
Avoid walls of words
rule of thumb – keep paragraphs to under 12 lines
Most paragraphs will be much shorter. (one liners are just fine)
Formatting
Avoid walls of words
rule of thumb – keep paragraphs to under 12 lines
Most paragraphs will be much shorter. (one liners are just fine)
Formatting
Margins – Use large margins to prevent pages looking too
busy
Typeface – 10 to 12 point, Times New Roman, Arial
Use ample “white Space” around figures, headings,
paragraphs, equations, & lists
Manage your time
Create and use a schedule
Give yourself time to edit
Team: divide and conquer, assign different sections to
different people, but then have one person organize, and re-write it to create
a smoothly flowing document (rather than a patchwork quilt of different writing
styles)
Graphics & Charts –
use numbered figure captions,
refer to the figure in the text by the number.
use numbered figure captions,
refer to the figure in the text by the number.
Tables
include a table heading. Heading go above tables (figure captions go below figures)
include a table heading. Heading go above tables (figure captions go below figures)