Tips on Technical Writing page 1 of 3 Tips on Technical Writing for MECE 2361
These are the “things” the instructor is looking for —so expect deductions if these tips are ignored. 1. Introduce your subject or report properly (in the Abstract and the Introduction). Writers and presenters commonly provide an insufficient introduction and/or insufficient information at the beginning. They fail to put the project in context…Why are you doing this project and for whom? This lapse is extremely critical in an oral presentation since the audience is left at the starting gate with little chance to recover. At least in a written report the reader may eventually discover the context somewhere and then return to reread the report with this new and necessary understanding. However, having to read the report twice means twice the work. Technical background is also very important (in the Introduction) so the audience can follow. Again, the technical background is critical in an oral presentation since you have only one “shot” at the audience. In a written document, the reader can “take a break” and seek alternative sources for technical background if needed. 2. All figures and tables have numbers and meaningful titles. Figure titles go below the figure; table titles go above the table. 3. All figures and tables must be cited in text. Best practice is to insert the figure or table “soon” after it is cited. 4. Make sure that you have included sufficient explanations for figures and tables. Figures and Tables can be very effective in communicating a lot of information in a very concise manner. They can also be useless if not properly explained. Axes, curves, and parameters should be identified on graphs. Figures with text notes and labeled arrows and pointers with summary explanations in their captions are much more effective than an extended narrative attempting to explain a figure. Table headings should be almost self-explanatory. You should strive to make all tables and figures self-explanatory. After all, many readers only look at the “pictures” and are unwilling to take the time to find the accompanying text. 5. All non-text “things” are probably either figures, tables or equations. “Pictures,” “plates,” “drawings,” “photographs,” or other such things are considered figures and should be so called. 6. Appendices are used for auxiliary figures, tables, equations, explanations, derivations, details, etc. Normally writers fail to take advantage of appendices and “load” up the main text with too many details, making it more difficult for the reader to following the important “stuff”. 7. Decide what you are going to call something (the “solution”, the “design”, the “artifact”, the “device”, etc.) and call it that throughout the report. Technical writing is about a complex Tips on Technical Writing page 2 of 3 design, process, experiment, etc., and your job is to make it easier for the reader to understand. Keep your sentences short and be consistent. 8. Avoid first and second person. “You” is sometimes appropriately used for “instructions” but be consistent. Never use “I” (unless absolutely necessary). First and second person are ok in a cover letter. 9. Make sure that lists contain parallel elements and are punctuated. Be consistent. It is particularly obvious in bulleted lists, but the same rules hold for items in the sentence elements separated by commas and “and”. 10. Avoid “this” and “that” used as pronouns; use them as adjectives especially at the beginning of the sentence. (If you cannot figure out what they refer to, how do you expect the reader to figure it out?) If you just have to use them as pronouns, make sure that the reference is clear. 11. Cover Letters: follow the suggested three paragraph format; sign the letter; space out the text; take it seriously; don’t copy it; state “attachment” at bottom. 12. Be consistent with capitalization for figure titles and labels, table titles and headers, references, etc. 13. Cover page (if required): make it attractive. (However, don’t use lots on downloaded colorful, but tasteless icons.) Include all the information asked for. 14. It’s = it is; its = possessive. 15. Normally equations are numbered and referenced: Exceptions: a.If there are only one or two equations in the report, numbering is not required. b.If there are many equations, it is acceptable to number only the ones that are referenced (i.e., the important ones). 16. All numbered equations should be referenced. (Otherwise why number them?). 17. Use the language of dimensioning properly and effectively. If you are claiming a plus or minus 10 feet uncertainty, do not write the dimension as 197 feet and 3.4 inches. Write: 200 ± 10 feet although one could make an argument for 197 ±10. 18. Do not use a narrative style. Use a concise, descriptive style. Most reports are much longer than they need to be. Learn to separate out the important stuff. Put the rest in an appendix. There is no need to repeat text with the possible exception of parts of the abstract, introduction, results and conclusions. 19. Know the differences between “etc.”, “e.g.”, and “i.e.” before you use them. 20. Be specific. What is “research” in the sentence: “We did some research and found that…..”? Tips on Technical Writing page 3 of 3 21. Beware of dangling or hanging participles, which are phrases, usually at the beginning of a sentence, starting with the “ing” form of a verb that has no reference, e.g., “Walking home yesterday, a tree fell on my head.” This example is not to be confused with a “verbal noun”, e.g., “Walking before bedtime helps me to sleep better.” 22. Be consistent in format: a. Hierarchical Headings b. Numbered Headings c. Paragraph length d. Fonts 23. Numbers: Definitely read about when to use “5” or “five.” Basically, numbers over ten or so are usually written in Arabic form: 14, 25, 110, and numbers below ten are usually written out in words, but there are many other rules. For example, don’t begin a sentence with an Arabic number. Also when having to “write” several numbers in one or adjacent sentences use the same form for as many as reasonable, e.g., there were eight boys and nineteen girls at the party; or there were 8 boys and 19 girls at the party. 24. Miscellaneous: Parentheses (Probably over used.) Dash (Do not overuse.) Sentence length (Keep it short!) Never end a sentence with a preposition? Never split an infinitive? Useless jargon (from the French: twittering): gobbledygook, techno-babble. Useful jargon — know your audience. Jargon can easily be over used and with an “uneducated” audience can be very un-beneficial. You can introduce acronyms into your documents, but be sure to define them (if appropriate – know your audience). Strictly speaking acronyms defined in the Abstract, must be redefined in the Body of the document (since the Abstract is considered a “stand alone” document). Do not start a sentence with an acronym.
Individual Project: A Concept for the Team Project #2 Draft Due: September 21st (Submit hard copy to Bannerot’s ME office mailbox by 5 PM) Draft Returned: October 3rd Final Report Due: October 17th The purpose of this project is to demonstrate that you can prepare and use drawings effectively to illustrate a proposed design solution (concepts). You will be illustrating a concept for a design that will satisfy the requirements for the Final Testing for Team Project #2. As a minimum you will produce two drawings: 1) an overview of the concept and 2) enlarged drawings of the one or more of the complex mechanisms utilized. Your goal is to make the drawings self-explanatory. It is not intended that you produce dimensioned “assembly” or “construction” drawings with surface finishes and materials specified. Rather, you are producing drawings to communicate your ideas for a concept. Materials and some important dimensions may be included, but you are being asked to provide only the “concept”. Annotated drawings (with text notes to point out features described in the text) are expected. Refer to the “Tips on Technical Writing” document to determine expectations of the instructor. Utilize the writing skills you acquired in ENGI 2304 and review the posted examples. NOTE: the instructions for the preparation of this project have changed over the years, so DO NOT copy the format of these examples. Follow these instructions for spring 2016. Double space the document. Your report should contain the following sections. Use the section titles indicated in bold. • INTRODUCTION (less than 150 words) The introduction should provide the following information o What is this document and why was it written (context)? o What is the problem (a problem statement)? o A summary of what is contained in the rest of the document? (not the description of your concept, but the fact that there is a description given.) • CONCEPT: (drawings plus about 400 words) The concept section should include a complete and detailed description of the concept proposed that includes at least two computer-generated drawings. Excellent, well-annotated, three-dimensional, computer generated drawings are expected. Use the text to explain the drawings; use the drawings to illustrate the text, i.e., work to integrate the text and the drawings. If you have access and experience with software capable of producing 2 acceptable drawings, the strong suggestion is to use it. If not, the suggestion is to use a free drawing package like Google SketchUp http://sketchup.google.com/ or TinkerCad https://tinkercad.com/home/ . If you are not experienced with a suitable drafting software, you are strongly urged to contact one of the TAs for help as soon as possible. (It will not do much good to wait until the assignment is due to seek help.) Note that all figures must be numbered, have a title and be referenced from the text. Consult the Tips on Technical Writing document. It is expected that you will follow the instructions exactly. Use a single staple in the upper left hand corner to secure the pages of the report (No cover sheet or letter of transmittal). Do not place the report into a “folder” or a “binder”. Use a header on the first page of the report similar to the one on this document plus your name. Submit a hard copy of the draft of your report on September 21st (Place a hard copy in Bannerot’s ME Office by 5 PM). If for some valid reason, you are unable to submit a hard copy by 5 PM, September 21st, you are strongly urged to contact the instructor via email. Grading penalties will result for late and/or electronic submissions. The draft will be reviewed and graded. Suggestions for impro