Appendix C. Technical Writing
Contents
1. skimmed Routine business documents include memos memorandums meeting agendas meeting minutes and notices Table C 1 shows a variety of other documents that are generated and distributed by groups Naturally this list is only a small sample of all of the different engineering functions and documents generated by engineers Every industry company and engineering profession has its own document types For the pur poses of brevity broad categories are provided for some very specific engineering functions This section discusses some documents used in various circumstances but is by no means complete One could argue that the lists of departments should include facilities research and development informa tion technology and more Engineering departments often receive documents that must be processed Table C 2 shows a vari ety of documents that are received by the various departments Some of the standard documents are described in the following list In some cases the format and content are specified by the customer company or profession A common form is memos short let ters to let others know about changes Given the freeform nature of memos they often travel within departments for information and requests Depending on the destination these documents have vary ing levels and types of details Letters of transmittal are similar but for groups outside the company For example the accounting department wants to know about exp2. Other external Design Research Development Production methods Engineering change notice Specifications and data sheets Market studies Life cycle Assessment uality requirements aterial requirements ill of materials for rojects mployee work reports urchase request Zo W U MO Position description Annual reviews Project proposals Project reports Executive briefs nvention disclosure form Patent support information Letter of transmittal Quotes proposals Manuals Specifications Consulting Technical and application notes Letter of transmittal or notice Regulatory reports Source Departments Manufacturing Fabrication Construction Assembly Engineer change requests Change notices Production forecasts Material orders Employee work reports Purchase request Position description Annual reviews Project proposals Project reports Production reports Letter of transmittal Shipping details Letter of transmittal or notice Patents Quality Testing DOE Prototype Laboratory report Environmental audits Quality audits Purchase request Material part certifications Position description Annual reviews Project proposals Test result Summaries Letter of transmittal Quality reports Certification Laboratory report Consulting Letter of transmittal or notice Environmental reports Standards testing e22 APPENDIX C Technical Writing Table C 2 Typical
3. when you know what you need to say The key to this approach is to do the technical work first Make a point of creating figures tables and calculations as you go Point form or short notes can be used to capture information that will be used when writing later 1 Background work 90 a Develop a single sentence description of the purpose for the report b Define the goals for the project clearly in bullet point form APPENDIX C Technical Writing e39 c Plan and do the work as normal Regardless of what the report entails this will often include creating sketches drawings graphs or charts of collected data pictures etc d As work continues on the project add notes and figures e The document outline is the technical exhibits and point form text in a logical order The content should tell the story by itself before the text is added 2 Structuring 5 a Do the analysis preferably on computer of the data and results These should be organized into a logical sequence b Review the results to ensure they make sense and follow a logical flow If necessary add figures to help clarify Write figure and table captions that describe the materials that will be included in your report c Review the materials to verify that they make sense without the text d Within the required sections write bullet form notes to lay out the document e Use your notes and other records to add bullet point information 3
4. Test certifications for a medical device C 31 Explain how the purpose of work should be described and answered at the start and end of a technical document C 32 Why are references important in technical documents C 33 Consider a document that includes both exhibits and text How should they be related Reference Strunk W White E B 2000 The Elements of Style fourth ed Pearson Further Reading Bryan W J Ed 1996 Management Skills Handbook A Practical Comprehensive Guide to Management American Society of Mechanical Engineers Region V Dhillon B S 1996 Engineering Design A Modern Approach Irwin Heldman K 2009 PMP Project Management Professional Exam Study Guide fifth ed Sybex Heerkens G R 2002 Project Management McGraw Hill Pritchard C 2004 The Project Management Communications Toolkit Artech House Ullman D G 1997 The Mechanical Design Process McGraw Hill Wysocki R K 2004 Project Management Process Improvement Artech House Zambruski M S 2009 A Standard for Enterprise Project Management CRC Press
5. Writing 5 a When the project is complete convert the bullet point form to full text b Verify that the report conforms to guidelines c Proofread and edit The writing process has inertia The first paragraph always seems to take too much time After the first paragraph is written the process becomes easier and faster Writer s block normally occurs when the next writing steps are not clear This will happen when we are not sure what we need to say why we need to say it or how we need to say it This can be caused by a lack of understanding of the topic or viewpoint Some simple strategies are provided in the following list for some of the common issues e Ifyou are unsure what to say stop step away from the writing figure it out then start again e Knowledge If you are not sure what you are writing about you should spend time clarifying your knowledge before returning to writing Reorganizing the material often helps to create clarity e Lack of knowledge Current knowledge is based on fundamental knowledge discovered and used before This means that no matter how simple something apparently is it has more layers of knowledge than could be known by any one person If you don t know everything you should define what you do and don t know e Skip that great opening paragraph It is quite acceptable to start by writing central sections of a report Many authors will write the abstract introduction and conclusions last
6. and reports The front matter may also include acknowledgments of technical sources funding agencies and technical assistance Dedications are often common and are brief mentions of a personal nature of friends family colleagues and the deceased e References and bibliographies In technical work it is important to cite the sources used The alternate is to cite no sources and then be responsible for justifying each item of data equation and design decision When readers come across a reference they may want to read more to understand the technical details Again without a reference you are responsible for providing these details A simple approach to references is to numerically list the author title publisher and year If it is a manual list the company name and manual title When Internet references are available provide hypertext links and the date you viewed it Use reference numbers in the report body for example 4 to find the reference There are other reference formats commonly used and it may be necessary to change the format near the end of the project A bibliography is a list e30 APPENDIX C Technical Writing of materials related to the work Footnotes are references that are at the bottom of the page that refers to them e Appendices When we have information that is needed to support a report but is too bulky to include one option is to add an appendix When material is placed in an appendix it must be summa
7. dia grams conductor placement and flow patterns Engineering drawings provide detailed geometries for solid parts Applications of these range from part placement on circuit boards piers for bridges tooling geometry bioreactor piping and pistons The conventions for drawings are very well understood although there are some variations between disciplines and applications Some of the general rules for technical drawings are General requirements e Use a title block with the top front side views distributed normally Isometric views are shown at an angle e Complete the title block with part name client date designer name dimensions material and default tolerances Orthographic views e There should be three views unless axial symmetry allows fewer e32 APPENDIX C Technical Writing e The front view should be the most descriptive e Blind holes made by drilling must have a drill point shown e All parts must be manufacturable e Avoid shaded drawings unless looking for interference or providing an aesthetic view Schematics and PCBs e Use multiple drawings for each functional system e Show where data buses enter and leave a drawing e Shown connectors and test points e Label all components and show polarities and orientations for parts e Add special labeling where critical e Position parts to minimize overlap on traces e If crossing conductors touch use a black dot to show electrical contact Dimensioni
8. is nothing to be said about a category use no changes nothing done or complete as appropriate e Executive summary or brief A condensed version of information to prompt or answer specific questions that a manager might have These can be less than one page in length or a few pages for a major project e Study or consulting report A study or research is done to investigate a topic of interest The important results are captured in a report These reports often end with conclusions suggestions or recommendations APPENDIX C Technical Writing e23 e Certification and regulation Government mandated and voluntary standards often call for publicly filed reports for health products environmental concerns transportation safety fire safety electromagnetic emissions etc These often come in defined formats and content They normally require design manufacturing and testing details The standards for health and aviation safety products are often noted as examples of complexity e Intellectual property e Patent Documentation that an idea was developed and disclosed by an inventor giving them 20 years of legal protection e Invention disclosure form Used to inform a company about something that might lead to a patent e Expense claim e Travel report Describes interactions with the customer knowledge learned issues etc Some business communication such as reports and expense claims are done using forms These allow
9. results Procedure The experimental method Equipment A list of the components and measurement equipment Results Measurements and observations from the test Analysis and discussion The data are processed and compared to the background and theory Conclusion Refer to the purpose and analysis and state whether they agree disagree or are inconclusive e Appendices Large volumes of results calculations or design work Test results normally follow the scientific method with some objective The results should be designed to conclusively prove the purpose hypothesis As a result most test reports include calcula tions numerical readings graphs tables and so on The outcome of the test should be summarized concisely and hopefully numerically in the conclusions Some of the common reasons for testing are Proving devices meet specifications Determining parameters for a device or system Establishing technical design limits Proving a prototype or concept Evaluating predictability APPENDIX C Technical Writing e29 PROBLEMS C 8 Why are abstracts used on large documents C 9 How should a design proposal and final report differ C 10 Does a report need figures if everything is described in text Explain C 11 How are the report conclusions related to the purpose C 12 Are sections on testing or fabrication required in design proposals Explain C 13 What section s might be added to a design proposal to present customer surv
10. screw screw etc Table C 4 lists a number of examples of reasonable replacements for complex phrases When edit ing or writing the default should be the simpler form The more complicated forms should only be used if there is a specific reason This list is not exhaustive and each dialect of English has unique phrases that have developed over time they may be accepted in one region but make no sense in another At the paragraph level and above there are strategic issues that impact the effectiveness of a document Reading sequence How can the document be read e Linear Read beginning to end in a fixed sequence reports and proposals e Nonlinear Read beginning to end in a variety of sequences e Random access Small sections of the documents are read as needed The message e State the objective or outcome for the work and repeatedly address it while writing e Use summaries to restate important points and put them in context e Consider the big picture Overview repeat while adding detail summarize e Interleave visual and written content e All statements should be justified avoid personal opinions or gut feels Technical Writing Standard ASD STE100 www asd stel 00 org APPENDIX C Technical Writing Good was reviewed with selected measured calculated calculated measured chose parallax error damper resistor build calculate write axle illustrates Table C 4 A Plain Englis
11. that each section is self contained and is easy to locate Providing a visual cue such as a title or figure will help draw readers to the section If the section relies on other knowledge provide links or references to the other sec tions In the first paragraph tell the reader what the section is about and how it concludes Some of the aspects of technical writing are listed below The key principle is that busy profes sionals are paid to write and read the documents Ideally they are written well the first time They are clear concise correct and the needed information is readily available The credibility of a report is based on the evidence it contains This evidence then supports the conclusions drawn or message given by the author The key in all written reports is that they can travel a long distance outside a company and become a formal record of commitments The purpose for the writing is clear including decisions recommendations and conclusions The format for the writing is standard and well known Somebody will use it The report contains many details The report may break various creative writing principles Entertainment is not the primary purpose e The report can have legal implications or be required by law regulation e19 e20 APPENDIX C Technical Writing PROBLEM C 1 Why should technical writing be as concise as possible C 1 Report and document types Assume that everything you say or write is only
12. variables before they are used This can be with a nomenclature page after the table of Keep solutions in variable form until the end of the problem then substitute numbers if required In engineering work numbers are important When representing numbers it is best to use engineer ing notation where all exponents are factors of 3 1 e 6 3 0 3 6 The rules of significant e34 APPENDIX C Technical Writing figures should be observed when using numbers but it is better to use variables and substitute num bers as the last step of a calculation Some of the rules for engineering numbers follow Put a space between numbers and units Verify that units match the numerical results Radians are one of the units that may not observe normal conventions Use engineering notation move exponents 3 places so that units are always in standard powers of micro milli kilo mega giga etc Avoid number formats such as 0 00000456 that include too many leading zeros e Use significant figures to round the numbers into meaningful values For example stating a length of 0 345432 inch for a dimension measured with a ruler is ridiculous e Units are always required e Take care to distinguish between frequency stated in Hertz versus radians s don t use cycles sec e Include a 0 before a leading decimal point such as 0 5 not just 5 PROBLEMS C 14 What is an exhibit C 15 How are appendices used to
13. APPENDIX Technical Writing Simply put writing is about the details the words are secondary A design report might include tab drawings part lists calculations procedures source code and schematics These graphic and tech nical details are essential to make the report understandable the text adds explanation and context A technical report with only text is very difficult to read and requires substantial effort by the reader Many people read textbooks by looking at the figures first and only read if the figures are not clear Readers value writing that provides the right details at the right time Naturally readers lose interest if the writer wanders off message is not concise and is not clear For examples of good writing find some textbooks that are highly regarded Consider how you read textbooks As mentioned most readers will look at the figures and details and then read text to resolve confusion some readers avoid reading the text altogether and focus only on the details You should always keep this in mind when communicating details first Make it easy for the reader Technical readers are less likely to read a report from beginning to end though some will The main approaches to reading technical documents are to 1 read everything 2 skip to sections of interest and read only those 3 skim and read selectively or 4 skip or skim and only look at the figures To write effectively for this audience you must assume
14. Documents Received by Design Manufacturing and Quality Departments Destination Department Manufacturing Source Design Research Fabrication Construction Department Development Assembly Quality Testing Design Manufacturing Sales marketing Specifications Orders or sales projections Quality testing Prototypes and pictures Request for quotes or proposals Design change requests Order change requests Accounting Expense account summary Expense account summary Expense account purchasing finance Invoices for verification Invoices for verification summary nvoices for verification Operations facilities Inventory logistics Bill of lading shipping Packing list Human resources Manager legal Procedures manual Procedures manual Procedures manual Project proposals Project proposals Copy of contracts Project reports Copy of contracts Executive briefs Copy of contracts Customer Letter of transmittal Letter of transmittal Letter of transmittal Other external Request for changes Letter of transmittal or notice Standards and regulations Failure and defect reports Letter of transmittal or notice Certification reports Laboratory reports Consulting reports Letter of transmittal or notice Presentations Environmental policies Regulatory policies White papers Presentations papers Presentations papers Patents ndependent test Studies reports since the last report as well as current action items If there
15. acronyms should be defined when first used An author has many choices concerning how to write a sentence and paragraph This style choice is a function of the words and structures used to communicate a message In technical writing this is mainly a function of precision Determine what you need to say and then express it clearly Adding unnecessary content and complication only creates barriers to the rate and depth of reader compre hension The guidelines shown in the following list should lead to better technical writing e Don t find creative ways to say technical things Many students have been taught that they should not repeat themselves and instead should find multiple ways to say things When this is done in technical documents it leads to confusion Authors should use precise terms as many times as needed and avoid trying to generate creative word choices For example we could increase confusion by also describing translation as motion movement sliding displacing etc e Keep it simple In an attempt to increase the prestige of their documents many authors will use uncommon or pretentious words This often leads to confusion and should be avoided In some cases when authors are unsure they will respond by making their writing style more complex but most readers recognize this For example Electronic computer based digital readings can provide a highly accurate data source to improve the quality of the ascertained data
16. could be replaced with Computer based data collection is more accurate e Clear concise and complete the three Cs In some courses students may have been required to write reports with a minimum number of words This requirement may have encouraged students to increase their verbiage However readers appreciate shorter documents that get to the point For example Readings of the pressure as the probe was ascending up the chimney toward the top were taken is better put Pressure probe readings were taken at multiple chimeny heights Also it is better to break complex ideas into smaller pieces e There is no great opening paragraph Many student authors spent a large amount of time on the opening paragraph to set the tone for the report All too often the longer a student tries to write the opening paragraph the worse it becomes In most cases these opening paragraphs can be deleted e36 APPENDIX C Technical Writing entirely from the document without any negative impact Ironically the writing of these students often improves once they get beyond the first paragraph but often they have already lost the interest of their readers e Transitions are not that important Students are often coached to create clean transitions between sentences and paragraphs As a result they often add unnecessary sentences and words to make these transitions Words that are warning signs include also and then Standard technical doc
17. d special headers and footers lie outside the margins Exhibits is a broad term covering nontext elements of a report These include items such as figures equations tables drawings and graphs When presenting exhibits the general principles are as follows e All visual elements e g figures and tables should have a descriptive title and number e Every exhibit should be referred to by number in the text e Image resolutions should be high enough to be clear Typically 300 dpi or more All important detail must be visible Avoid pixelation APPENDIX C Technical Writing e31 If there is too much detail put it in an appendix Photographs and drawings should be cropped to size and clearly visible Screen captures should be clear and complete but other detail is cropped out Color exhibits can still be used if printed in black and white Like reports figures are used throughout this book to illustrate concepts Each figure should have a unique title that clearly and concisely describes what is shown Nearby text refers to each figure by number and has a related discussion Some of the general attributes of figures are e Figure content can include drawings schematics graphs charts etc e A figure should be labeled underneath sequentially and given a brief title to distinguish it from other graphs For example Figure 1 Voltage and currents for 50 ohm resistor e In the body of the report the reference may be shortened t
18. e Your report doesn t need to sound impressive Simply write what you mean to say If you are having trouble saying it skip it and come back later or leave it out if you can e If you feel like you are babbling then consider adding a figure or other exhibit The single largest mistake that engineers make is to start writing before assembling the technical content Given that the end product is the written word it is obvious to start there The writing in a report is analogous to a new house that is finished with paint and carpet Behind the finish materials there is technical framing and service work that holds it together To start reports with writing is akin to trying to build a house by painting and carpeting first A good professional will prepare the plans and background materials first and then the finishing touches of writing hold it together e40 APPENDIX C Technical Writing PROBLEMS C 25 Explain how the exhibits in a report are like a rough draft of an essay C 26 If you are writing and you feel confused what should you do C 27 When somebody says you will write a report does that mean that you will spend most of the time writing INSTRUCTOR PROBLEMS C 28 Is writing text the most important step in writing a report C 29 What are the three Cs of communication C 30 Describe reasonable audience expectations for the following a A software user manual b An automobile mechanics manual c A project proposal d
19. e general APPENDIX C Technical Writing e35 problems encountered when writing technical reports along with some strategies for fixing these problems An excellent reference for this type of writing is Strunk and White 2000 e Basic spelling A document should always be checked for spelling Considering that utilities for checking spelling are available in most software and operating systems this is expected Be aware that spell checkers will only point out misspelled words not words used inappropriately so you should also proofread e Technical spelling Many technical terms are not in the dictionaries used for checking spelling You may add these terms to the dictionary or visually verify Be very careful when using the auto replace options in software e Basic grammar Grammar checkers can be used to look for obvious problems Using simple sentence structures will reduce problems and speed the writing process Grammar checking software should not be used as a replacement for proofreading e Technical grammar Normally grammar checking software will reject text written in passive voice but the software can often be reconfigured This software will also be confused by the interchangeable use of nouns and verbs common in technical English such as input e Jargon and acronyms A number of technical terms and acronyms have been developed for efficiency and clarity Examples include DMM HTTP kitted parted etc All
20. edule Financial details Payments and hold backs Proposal format Approach deliverables schedule budget ability to do work Evaluation criteria Lowest cost ability to do work etc Quotations or contracts Formal documents that outline the work to be done and obligations normally includes delivery schedules specifications warranties and payments Details are critical in these documents Some of the lists provided in Appendix A as thought starters for project and detailed design documents Additional components will be needed for special design work company requirements and so on For example designing parts for aviation and medi cal markets have particularly complex design requirements and documentation Manuals and user documentation are normally required at the end of a project These can be writ ten by the engineers or by a technical writer In either case the engineers are responsible for generat ing the technical content in a form that is suitable for the audience Additional writing typesetting illustration proofreading and legal text may be added after Typical examples of manuals and similar documents are shown in the following list Sometimes documents such as a quick start guide can be left until the end of the project Others should be created as the project progresses for example docu mentation for a programming interface User manuals Programming manuals Maintenance manuals APPENDIX C Technical Wri
21. enses and how to apply them to specific jobs Managers want to know about the need for new resources and the progress of existing work The customer primarily cares about the progress of their order and expected delivery dates e Memorandum A memorandum or memo is an internal business communication or brief technical report designed to convey a business policy or technical information The standard memo starts with the header Memorandum Date From To Subject cc e Letter of transmittal or notice When a document is sent between companies a letter of transmittal is often sent to describe the purpose for the document A notice is similar to a memo but it is directed to a customer for information purposes e Interim or progress report A progress report provides details of project progress to a supervisor or customer Teams are sometimes required to submit progress reports as often as weekly These reports may include several elements divided into sections with a heading for each Point form is common but complete sentences should be used Each section should include items completed APPENDIX C Technical Writing e21 Table C 1 Typical Documents Sent by Design Manufacturing and Quality Departments Destination Department Design Manufacturing Sales marketing Quality testing Accounting purchasing finance Operations facilities Inventory logistics shipping Human resources Manager legal Customer
22. ey data and QFD C 2 Document formatting The format of a document is used to organize and convey information in a consistent way In tech nical documents the formatting ensures that the figures equations data tables and text are tied together in a consistent and logical manner The obvious rule is to select a format and then apply it consistently Some of the common variations in technical documents are described here including section numbering fonts and references e Page numbering Most software makes the process of numbering pages quite simple Before the first page of the body of the document the pages are numbered using roman numerals For example page i may be the first page of the table of contents The sequence starts again with Arabic numerals starting at 1 on the first page of the body Sometimes in technical documents the pages are numbered by chapter for example 4 7 would be the 7th page in the 4th section This can be helpful if you want to replace or break larger manuals into replaceable parts When pages are blank they should still be numbered and contain the words this page left blank intentionally This will eliminate concerns about missing or misprinted pages e Front matter The title page contents listing any foreward preface or introduction are all considered front matter they appear at the front of the document Copyrights are added to the beginning of many documents including manuals
23. g The standard for larger documents are 1 Chapters 1 1 Sections and 1 1 2 Subsections This convention is well understood and simplifies the relationship between the table of contents and the report sections In short reports the numbers may be omitted but a different heading style should be used for the three types of headings to distinguish them from one another e g all caps title case title case and italics etc e Page size Many documents are no longer printed but if they are the standard paper sizes are US Letter and A4 Metric If distributing a document in a fixed file format such as PDF the author should produce two versions for each paper size or one version that can be reasonably printed on either Distributing documents in an editable file format such as DOC or ODF allows easy resizing for different printers For electronic formats such as web pages and help files the text should be broken into smaller separate sections typically a screen length in size e Fonts Standard document fonts are normally 10 to 12 points Bold italic and underlined fonts are used sparingly for emphasis Larger fonts are often used for section headings and titles e Margins Borders of 2 5cm or inch allow visual gaps to help the reader In addition most printers cannot print to the edge of a sheet For left right facing pages an extra gap is left by the binding to compensate for the visible area lost to the center crease Often page numbers an
24. h Translation Chart Bad it became obvious that came in at in order to be needed to be needed to be used decided to be so as to can be located found to have found through it was found that implementation of important precise exact perfect noted to be involved allowed for it was found to be was looked thorough along with decided on found the wearing of needed to found read optimized human error dampener makes things wet resister Someone who resists create axel represents Negative statements may be necessary e Communicate issues clearly without vague language to soften the impact e Reduce surprises later e It sends a message that more support resources may be needed e It encourages trust Technical depth and completeness e Provide the level of detail suitable for the audience or provide references if needed e37 e38 APPENDIX C Technical Writing e Follow the problem solving approach normally used by the audience e Ask the question Could somebody understand my work if I were not here to answer questions e If you were to restart your work would your report help you save time and effort e Consider that many of the readers do not have English as a first language or do not know many of the phrases you do Procedure e Proofread as you write it will be easier to correct e There are no rewards for flowery creative and poetic language e The main purpose
25. hese are used as reminders In practical terms notes are used for generating reports and more These are often done on pads of paper in notebooks or by computer When used as a legal record for patent and liability reasons the process is formalized Legally acceptable notes are written in pen in engineering notebooks with numbered pages stitched in to prevent removal These are reviewed and notarized regularly The notes in the books are meant to be added sequentially as the work is done with dates and times included An alternative is to take voice memos and have them typed later a very common approach in the medical fields At times professionals will present information to other professionals One example is white papers which are very similar to academic papers These are done for technical audiences with the purpose of informing and educating White papers are produced in large numbers by companies developing cutting edge engineering tools and materials Similar documents include design guides reference designs and data sheets These are less about education and more about providing guidance to a knowledgeable design professional Engineers will occasionally create materials for audiences with less time to read or those who possess less technical knowledge In such cases a presentation or poster may be used A poster is a e28 APPENDIX C Technical Writing large printed format that conveys the key information visually so that a spectator ca
26. however these may be de emphasized or omitted in final reports Typical proposal and report elements are shown in the following list It is worth noting that some organizations may not require a written report but they do need the technical content of the report e Cover page e A title that allows the work to be easily identified e The name of the authors or originating company department class etc e Publication date or document tracking number e Executive summary or abstract e A very concise overview of the work and outcomes e Unlike fiction it should give away the end of the story e The reader should know what to expect if they read the report e Many readers will only get the information in the summary so make it count e Table of contents For documents with more than 10 pages e Should provide the major topical divisions for easy access e May include lists of tables and figures e Nomenclature For documents with extensive calculations e List all variables used in the report e The order is upper then lower case alphabetically with regular letters followed by Greek e Descriptions and units should be included e Introduction e Provide the motivation and objectives for the work e Give essential details e Research should be documented with a literature review e Design These sections are included when design work has been done e Background Sponsor project needs e Specifications e Concepts A template for a design proposal or final repo
27. improve the readability of reports C 16 Why are equations numbered C 17 Should every table and figure be mentioned in the text Explain C 18 Why are references useful in technical reports C 19 Why should a zero be placed before a decimal point when a number is less than 1 C 3 Technical style grammar and syntax Consider the writing style you appreciate Technical writing is different than writing for entertainment or persuasion This is not to say that tech nical writing cannot be entertaining or persuasive but the primary goal is to document and describe This leads to the three Cs of clarity conciseness and completeness Clarity is important when deal ing with complicated topics but this is easily lost with vague text Correctness avoids problems with mixed messages or simply incorrect details Conciseness is critical to keep the discussion focused and easier to absorb When writing is complete it will provide the details needed for understanding To begin with the obvious fundamental spelling and grammar are important Spelling and gram mar mistakes are a source of confusion and misunderstanding For example a point form sentence that reads e Increase the resistors might mean Increase the resistance or it may mean e Add more resistors Correctness comes in two forms One is the basic construction of the language syn tax and grammar The other is the technical content The following list indicates some of th
28. in Table C 3 Calculations and equations are required to justify design work These should follow the conven tions of the discipline For example Figure C 1 shows a set of calculations for a slip tip problem from a statics course with summed forces in Equations C 1 and C 2 Some of the rules for documenting calculations are e When presenting equations use a good equation editor and watch to make sure fine details like subscripts are visible e Number equations that are referred to in the text e Box in equations of great significance APPENDIX C Technical Writing e33 Table C 3 A Comparison of Toy Vehicle Properties Mirror Description Mass kg Color Shape Material Car 3 Red Rectangular Die cast Truck 6 Blue Long Polypropylene Motorcycle 2 Green Small Aluminum CA P LR T sin 60 Fp sin Og 0 ae iG 2 4 YF T T cos 60 Fp cos Og 0 ae substitute C 1 into C 2 _ T sin60 Ti T cos 60 sin Op cosOp sin60 _ sinOg a eae T e l tan Op 1 cos60 cosOp 866 tanOp i105 Op 30 98 sin 60 Fpsin 30 lt Fp 170N FIGURE C 1 Sample calculation to resolve force components Left justify equations or center all equations by the equals sign Express results in engineering notation Use subscripts consistently Highlight final results with a box equation number bold font or equivalent contents When possible italicize variables Define
29. information to be provided in a condensed format that is tailored to an application For rou tine and repetitive information forms are easily constructed to obtain a complete set of information in a format that is easy to read Although mundane engineers may consider developing and using forms for items such as design change requests ordering parts quality reports work orders customer estimates equipment scheduling sales engineering work sheets quote check sheets machine shop instructions PCB design rules test data reports and onsite data commissioning A paper or elec tronic form is laid out to collect the essential required and other information as necessary Engineers designing systems that involve other people should consider developing forms to guide the flow of information PROBLEMS C 2 List five documents for communicating between the accounting department and manufacturing C 3 What are five characteristics of a memo C 4 Why do businesses develop forms C 1 1 Project documents Project documents allow the developer or team to record all of the design decisions made during the course of the project This report should also mention avenues not taken Quite often the projects that we start will be handed off to others after a period of time In many cases they will not have the opportunity to talk to us or we may not have the time so the project report serves as a well known central document that includes all relevan
30. n grasp the con cept of the project at a glance and review the key concepts in under one minute The layout of the poster should be very visual favoring figures pictures and graphs Good practices for posters are described in the following list e Begin with a purpose and motivation for the work and a conclusion that refers back to the purpose Describe the approach of the work Acknowledge others who have contributed to the work Use colors to make it attractive avoid gaudy appearances Use visual images to speed comprehension Use a high quality printing and mounting process Glossy paper on foam core boards is standard Use large fonts and condensed text A few bullet point sentences with 16 to 24 point fonts is recommended The poster should be self explanatory e Avoid trying to present too much detail Testing has an objective of proving some hypothesis Engineering examples includes proof that a design meets the specifications or the statistical deviation of a material property In school laborato ries it is common to validate academic theory and investigate natural properties In companies tests are used to determine operation and customer needs There are companies that exclusively deal with testing as an independent source of certification Test reports are often documented using the follow ing format Purpose A clear objective or hypothesis for the test work Background and theory The basis for comparing the expected
31. ng e The location and size of each feature must be clearly defined e Critical assembly dimensions must be directly readable and not require addition e Holes that form patterns must be dimensioned relative to each other and relative to a major feature e Smaller dimensions should be closer to the part e Chained dimensions must be aligned e Hole sizes and dimensions should be on the profile view e Arcs circles more than 180 are sized by diameter otherwise the radius is used e Redundant dimensions should be eliminated Tolerancing e Tolerances must be reasonable for manufacturing capabilities e Tolerances must ensure proper assembly and operation at maximum minimum material conditions e Mating parts should not have identical dimensions they should be free running or press fits e Smaller tolerances should be used for mating parts e A general part tolerance should be defined for the part and smaller tolerances indicated for critical dimensions to reduce clutter Tables present information that can be structured into a small number of categories These allow details to be presented in a compact form that is easy to read General rules of form for tables are 1 a numbered descriptive title is shown above 2 row and column headings provide adequate descrip tions and suitable units 3 the table data should be readable and 4 the table should be described or called out in nearby text These principles are illustrated
32. o Fig 1 e The figures do not need to immediately follow the reference but they should be kept in sequence Often figures are moved to make the typesetting work out better Graphs and charts present data in standard formats including line bar pie and scatter Given that the data are numerical in nature there are a number of good practices as summarized in the following list If fitting a line curve to the points indicate the method used e g linear regression Try not to use more than five curves on the same graph Use legends that can be seen in black and white Clearly label units and scales on each axis Label axes with descriptive term For example Hardness RHC scale instead of RHC Scale the curve to make good use of open spaces on the graph Avoid overly busy graphs Titles should indicate clearly and distinctly why the content of the figure is significant Points should be drawn and connected with straight or no lines if experimental Smooth lines are drawn for functions or fitted curves If a curve has been fitted the fitting method should be described e Ifusing graphing software don t put a title on the graph Sketches are hand drawn or created using simple drawing software Unlike drawings these are not meant to be geometrically accurate Sketches are normally used in the early stages of designs to show concepts They will also be used for illustration in detailed design work including free body
33. of the text is to clarify not present the details e Textbook rule Write in the style you prefer to read such as textbooks manuals or guides e The 90 10 rule 90 preparation 10 writing at the end is good e 90 writing 90 preparation is not a good method PROBLEMS C 20 Should a technical report keep the reader s interest by finding interesting variations for names and operations C 21 Why is it better to state the outcome at the beginning of a report The alternative is to save it to the end of the report to surprise the reader C 22 What do the three Cs mean C 23 When is past tense or passive voice useful in technical writing C 24 What are three advantages and three disadvantages of using jargon and acronyms C 4 Writing process A good report can be described in one sentence An effective technical writer will not write text until the other work is done A poor writer will begin to write first and then fill in details as needed Outlines are the key to organization Simple outlines are sets of bullet points that can be rearranged until they make sense Technical outlines also include calculations specifications drawings sketches test results and much more In other words a poor writer will rush to write a good writer will do all of the background work first An effective proce dure for writing engineering reports is outlined in the following list This procedure leaves writing to a later stage
34. rized in the body of the report The report should briefly summarize usually a figure graph table equation or more and then refer to the appendix It is expected that the material summarized in the body will also appear in the appendices Examples of appendices include e Sample calculations These are redundant numerical calculations or a prolonged derivation of equations The body of the report has a summary of key assumptions sample calculations and results The calculations are often provided so that the reader may verify the work e Long tables of data Tables of numerical data are often put in appendices Typically a sample of the table is included in the body for discussion purposes The additional data are often provided for the reader who has a use for it beyond the uses in the report e Program listings Long listings of computer programs are often put in appendices They are referenced in the body of the report near the algorithm calculation or method they implement These listings are provided for readers who want to use the program e Multiple data graphs Multiple sets of data graphs are often put in appendices and summarized in a report body The graphs are provided so that the reader may use the graphs for verification or further analysis e Reviews of basic theory These are often referenced in the body of the report for readers who may not have seen a topic previously These are uncommon in student reports e Section numberin
35. rt is included on this book s website www engineeringdesignprojects com home content communication and documentation APPENDIX C Technical Writing e27 e Embodiment e Detailed design e Construction or fabrication e Equipment and materials required e Special instructions e Discuss equipment tooling components testing etc e Testing Testing objectives or hypothesis Experimental procedure Data collection and observations Basic data analysis and hypothesis testing and verification Statement of hypothesis proof or qualification e Conclusions and recommendations Discuss testing results Outline new knowledge and lessons learned Recommend a future course of action Discuss the fitness of the design or work with respect to the original motivation Summarize the report content so that the reader can verify his or her knowledge Repeat the significant results from the body of the report that the reader must know Tables and graphics can be useful for effective presentation e Appendices For essential detail too large for the body of the report Appendix Drawings Appendix Schematics Appendix Source code Appendix Detailed budgets Appendix Calculations Appendix Extensive data eoeeeeee e o o eoeeeee Working notes and notebooks are maintained by most professionals throughout the day In meet ings they will keep track of who said what what commitments were made when things are due problems successes and so on At a minimum t
36. sioning and acceptance reports are useful when a new design is being passed from a design team to a customer during a hand off procedure These reports document the testing results that show that the design satisfies all of the specifications and other standards They are also used to document agreement between designers and customers The commissioning or acceptance report should contain the following Inspections Visual mechanical electrical Installation Mechanical electrical production safety Testing Operates meets specifications reliable Other issues Deficiencies maintenance etc PROBLEMS C 5 List five documents that might be delivered to a customer at the end of a project e26 APPENDIX C Technical Writing C 6 Why are project charters and statements of work used to start projects C 7 Give a reason why a user manual might include a schematic or mechanical drawing C 1 2 Technical documents Write reports not mystery novels give away the ending Design proposals theses and final reports have overlapping content but with different objectives The design proposal is used to present all of the design details in a single document Throughout the project the amount of design detail in the body increases At the end of the project the test results sec tion is completed A great deal of attention is paid to the concepts embodiments budget timeline and other project planning details at the beginning of a project
37. t information The project report should include the following e Project charter A document to launch a project e Summary Title initiating person start and end dates customer crude labor budget estimates e People A list of key people and groups involved within the team e Scope and objectives An outline of the project at a high level e24 e e APPENDIX C Technical Writing Stakeholders audience A list of other major groups involved outside of the team Primary stakeholders Management related departments unions creditors customers suppliers contractors legal and regulatory bodies employees etc Secondary stakeholders Social political groups competitors communities public service groups professional groups media schools hospitals families etc Timeline Major milestones and dates Approvals Signed or equivalent permission to start Statement of work SOW Defines the scope of the project eoeeeeee Summary of details Approach The expected path for the work Strategies Priorities and fallbacks Timeline Scope What is and is not part of the project Assessment metrics Processes for communication and agreement between customer and supplier Request for proposals typical elements include the following e o o Statement of work SOW Requirements for work Deliverables Access services equipment provided Approvals required Contract type Major dates and sch
38. ting e25 Operator guides Training materials Safety labeling Design manuals Reference designs and design guides Tutorials and quick start guides Specifications Marketing materials Certification paperwork for legal reasons Test results and qualifications For the most part these guides should be written at or a little below the target audience Always assume that the documents will not be read front to back Many people do not refer to these manu als until there is a problem and they need to find a clear answer Well written quick start guides and manuals can avoid customer frustration rejected products and help desk calls Good practices to use when creating manuals include Provide safety warnings in all places related to safety issues Use pictures when possible Include warnings and legal disclaimers Provide revision numbers and dates Use numbered steps for procedures Provide checklists for inspections and maintenance Include troubleshooting information don t forget error codes Keep it specific complete and easy to understand Accuracy is key All of these documents can result in liability issues if incorrect or incomplete An index and detailed table of contents will make it easy to find details quickly Employ a technical writer or graphic designer for public documents Binding for paper documents and electronic formats are useful A website is helpful when customer copies of documentation are lost Commis
39. uments have standard structural forms that provide the major transitions for readers e Don t keep the good stuff to the end Many student authors try to write their reports so that there is a climax It can be very frustrating for a technical reader to have to read 90 of a report before he or she encounters some discussion of the results A technical report is not a mystery novel e Saying it more than once is acceptable Most student authors feel that it is unacceptable to state a fact more than once In truth you want to state fact as many times as necessary to make a technical point In the case of very important details they will be stated in the abstract the introduction the discussion and the conclusion sections e Colloquialisms Avoid informal language in technical reports Use of informal language such as cookin with gas will look unprofessional confuse some readers and easily dates the material e Repetition Early writing instruction often encourages writers to find interesting descriptions and variations As a writing tool this does help students explore the language On the other hand a professional has a collection of technical words and phrases with specific meanings Even at the risk of seeming repetitive these should always be used the same way each time Consider the example of an author who describes a specific screw with the following variations threaded shaft slot head threaded fastener M20 retaining
Download Pdf Manuals
Related Search