Guidelines for Writing Noise-Free Engineering Documents�

E. Esra'a Hyarat

Discuss the overall process used by successful engineering writers and include important considerations for your entire writing process.

​

Represent common problems you as an engineer are likely to face in the course of writing and formatting your documents.

SOME GUIDELINES FOR GOOD ENGINEERING WRITING

1. Focus on WHY YOU ARE WRITING
2. Focus on Your READERS
3. Satisfy Document Specifications
4. Get to the Point
5. Provide Accurate Information
6. Present your Material Logically
7. Explain the Technical to No specialists

SOME GUIDELINES FOR GOOD ENGINEERING WRITING

8. Make your Ideas Accessible

9. Use Efficient Wording

10. Format your Pages Carefully

11. Express Yourself Clearly

12. Manage Your Time Efficiently

13. Edit at Different Levels

14. Share the Load: Write as a Team

1. Focus on why you are writing

• Before starting to write, you should have a good idea of precisely what you want to communicate to your audience

​

• If these goals are not first defined in your own mind, you can’t really expect your readers to get a clear message

​

• Broadly speaking the purpose of most technical writing is either to present information, or to persuade people to act or think in a certain way. However frequently your documents will have to be both informative and persuasive

• Inform: provide information without necessarily expecting any action on the part of my reader(s)?

​

• Request: Obtain permission, information, approval, or help?

​

• Instruct: Give information in the form of directions, instructions, procedures so my readers will be able to do something?

​

• Propose: Suggest a plan of action or respond to a request for a proposal?

6

Questions to be asked before writing, Do I Want to…..

2. Focus on your readers

7

For Example

Ch2

8

​

• Any document should be guided by:

​

A. what you want your audience to do with your information

​

B. what they need from the document to be able to do it.

​

• Thus your audience plays a defining role in determining how you approach your task

9

• Recommend: suggest an action or series of actions based on alternative possibilities that you’ve evaluated

​

• Persuade: convince or “sell” your readers, or change their behavior or attitudes based on what you feel to be valid opinion or evidence

​

• Record: document for the record how something was researched, carried out tested, altered or repaired (report)

​

10

3. Satisfy Document Specifications

Before writing, you should be aware of any specifications your document must meet.

​

• Number of pages
• You may need to provide short summary
• Headings, fonts, figures size, margins...etc.
• Certain topics in your report (writing about specific thing)

​

e.g., request for proposal for a government research program

​

Each proposal shall consist of not more than five single spaced pages plus a cover page, a budget page, a summary page of no more than 300 words, and a page detailing current research funding. All text shall be printed in single-column format on 8.5*11 inch paper with margins of at least one inch on all sides

• If management asks for a brief memo, they may be irritated when you overload their circuits with a lengthy, detailed treatise.

​

• When a technician requests the specs on a frequency tester, it won’t be appreciated if you write about the strengths and weaknesses of the equipment.

​

• If you respond to an RFP (request for proposal) that calls for a proposal of no more than ten pages but submit something twice that long, your proposal will likely be eliminated from the competition.

12

4. Get to the point

• Provide the most important information at the places where the readers can access easily and efficiently

​

• The most important information need to be at the beginning

​

Example

• SUBJECT: Employee safety (Vague)

​

• SUBJECT: Need for employees to wear hard hats and safety glasses (Better)

13

5. Provide Accurate Information

Even the clearest writing is useless when the information it conveys is wrong.

​

If you state that an ampere is defined as a coulomb of charges passing a given point in 10 seconds rather than 1 second, you have presented wrong information.

​

If you refer to data in Appendix B of your report when you mean Appendix D, the error could stump your readers and cause them to lose confidence in your report

Ch2

14

6. Present your material logically

​

• Not only should it be easy to access your document’s essential message, but the parts of your information should be sequenced appropriately.

​

• You must organize your material so that each idea, point, and section is clearly and logically laid out within an appropriate overall pattern

​

• As always think before writing and keep your readers firmly in mind

15

7. Explain the Technical to�Non Specialists

Explaining the technical is a lot about knowing some tools and using them intelligently:

​

1. Definitions: One of your most important tools is defining potentially unfamiliar terms.
2. Examples: For non specialists, examples are a big help in understanding the technical
3. Importance: For some readers, discussing the importance of a topic helps them to wake them up and pay attention.
4. Uses and applications: People also wake up and pay attention when you explain how something can be used to good advantage.

​

5. Causes and effects (or reasons); problems and solutions; questions and answers: It helps to discuss these pairs of information types.

6. Categories: Discussing the categories of a topic can help readers gain a broader understanding of the topic

​

7. In-other-words explanations: When you’ve written something technical and you are not sure readers will understand, try restating it in simpler words.

​

8. History: For some readers, it helps to know the historical background associated with a topic

Ch2

18

• Structure your material in an easy way:

A. Subdivision of material into sections and subsections

with hierarchical headings and subheadings

​

B. Don't use long paragraphs

8. Make Your Ideas Accessible

Hierarchical Headings

​

Even in short engineering documents, a system of headings is essential to keep your material clearly organized and to let readers know what is in each section of the document. Headings and subheadings are also signposts that help a reader to get through a report without getting lost or to go to a specific point in the report

​

​

Example

​

FIRST LEVEL 1. QUALITY ASSURANCE PROVISIONS

Second Level 1.1 Contractor’s Responsibility

Third Level 1.1.1 Component and material inspection

Fourth Level 1.1.1.1 Laminated material certification

19

Paragraph Length

​

No one, especially in technical fields, wants to read a solid page of wall-to-wall text of difficult material. A busy manager, for example will want to absorb your information in as easily digestible pieces as possible.

​

Remember that:

​

1. Dense text on a page creates noise simply because it is too discouraging.

​

2. Technical information are usually demanding, so present material in short straight forward manner

​

3. A paragraph in technical writing should not be longer than 12 lines at max.

Use lists for some information

​

• A well-organized list is the most efficient way to communicate information.
• If you have to present steps in a procedure, materials to be purchased, items to be considered, reasons for a decision or groceries to be bought, a list might well be the best way to go because readers retrieve information from a list more easily and faster

​

21

Example describing procedures to install software

To install the Microsoft office software, turn on your computer, then insert the CD of office. Click on the icon setup, then make sure you interred the key number, then click ok. You can do better if you list the procedures

1. Turn on your computer

2. Insert Microsoft office CD .

3. Click on the icon "setup“

4. Inter …….

​

Ch2

22

Types of lists

• Numbered lists
• Check lists

It is a list where you have to check the items that apply

1. Connect the monitor to the computer

2. Connect the keyboard and mouse to the computer

3. Connect the power supply to the computer …

​

• Bulleted lists

Bulleted lists are commonly used when items in the list are in no specific order, as in the following example.

• Air pollution control
• Public water supply
• Wastewater
• Solid waste disposal

23

9. Use Efficient Wording

• Use simple words as you can

​

• Do not repeat words with same meaning (Redundancy) Like: The parts of the machine are connected together (connected and together have the same meaning)

​

• Unnecessary Passive Voice:

In the technical world, you must use the passive voice; but when it is misused, it leads to unclear, wordy, and even dangerous writing.

​

• Avoid A grammar mistake

Ch2

24

10. Format your pages carefully

• Margins: Leave consistent margin around your text. Standard around 1 in. (2.5 cm)

​

• Typeface: Serif (as Times New Roman) for body text, which is traditionally used by books, magazines, and newspapers

sans-serif (as Arial) are traditionally used fortitles and headings. They are also preferred for online text.

​

• Font size: Standard size 10 or 12 (For specific locations you may larger or smaller

​

• White spaces: single or double space

​

Ch2

25

11. Express yourself carefully

Ambiguity, Vagueness, and Directness

​

• Ambiguity. The word ambiguous comes from a Latin word meaning to be undecided. Ambiguity primarily results from permitting words like they and it to point to more than one possible referent in a sentence, or from using short descriptive phrases that could refer to two or more parts of a sentence.

​

​

Example:

Ambiguous: Before accepting materials from the new subcontractors, we should make sure they meet our requirements.(What or who——the materials or subcontractors?)

Clear: Before we accept them, we should make sure the materials from the new subcontractors meet our requirements.

• Vagueness:

​

If ambiguity involves more than one meaning, vagueness involves no useful meaning at all. What would you think if your doctor told you to ‘‘take a few of these pills every so often’’?

​

​

• Directness.

Being as direct as possible in your writing lets your reader grasp your point quickly. A busy technical reader wants access to your information quickly and easily. The most important part of your message should come at the beginning of your sentences and paragraphs

Ch2

27

12. Manage Your Time Efficiently�

• Finding and using time
• Make outlines for what you are going to write
• Put a timeline (schedule) including the deadline for completion the final version

​

13. Edit at Different Levels�

• Rather than expecting to randomly find anything in need of improvement, many writers prefer a more methodical approach to editing.
• First, check your document for technical accuracy.
• Then decide what ‘‘writing levels’’ to approach your editing on, and go through your document at least once on each level.

Ch2

29

14. Share the load: write as a team

​

• Communicate

​

• Coordinate

​

• Collaborate

​

• Compromise

30