Guidelines for Writing Noise-Free Engineering Documents

1. Guidelines for Writing Noise-Free Engineering Documents

2. 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.

3. SOME GUIDELINES FOR GOOD ENGINEERING WRITING • Focus on WHY YOU ARE WRITING • Focus on Your READERS • Satisfy Document Specifications • Get to the Point • Provide Accurate Information • Present your Material Logically • Explain the Technical to No specialists

4. 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

5. 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

6. Questions to be asked before writing, Do I Want to….. • 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?

7. 2. Focus on your readers

8. For Example Ch2

9. 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

10. 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)

11. 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

12. 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.

13. 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)

14. 5. Provide Accurate Information Even the clearest writing is useless when the information it conveys is wrong. Ifyou 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. Ifyou 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

15. 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

16. 7. Explain the Technical toNon Specialists Explaining the technical is a lot about knowing some tools and using them intelligently: • Definitions: One of your most important tools is defining potentially unfamiliar terms. • Examples: For non specialists, examples are a big help in understanding the technical • Importance: For some readers, discussing the importance of a topic helps them to wake them up and pay attention. • Uses and applications: People also wake up and pay attention when you explain how something can be used to good advantage.

17. 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

18. 8. Make Your Ideas Accessible • 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 Ch2

19. 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

20. 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.

21. 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

22. 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

23. 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

24. 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

25. 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

26. 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.

27. 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

28. 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

29. 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

30. 14. Share the load: write as a team • Communicate • Coordinate • Collaborate • Compromise