Download TECHNICAL REPORT WRITING GUIDELINES and more Study notes Design Patterns in PDF only on Docsity!
TECHNICAL REPORT
WRITING GUIDELINES
Prepared by
LEAH M. AKINS and JEFFERSON H. AKINS
for
TECHNICAL/ENGINEERING STUDENTS
ABSTRACT
This document specifies the recommended format to be used when submitting a formal
technical report in a variety of disciplines and purposes. Also, this manual can be used as a guide
to compose less formal reports, such as lab reports, that may consist of a subset of the items
presented here. It is a useful general guide from which faculty can specify the particular
requirements for reports in their courses.
Original Work: January 13, 2001
Current Revision: January 2009
D U T C H E S S C O M M U N I T Y C O L L E G E
P O U G H K E E P S I E , N E W Y O R K
Table of Contents
- INTRODUCTION
- THE FORMAL TECHNICAL REPORT
- UNIVERSAL ASPECTS OF ALL REPORTS
- REPORT FORMAT
- TITLE PAGE
- ABSTRACT
- TABLE OF CONTENTS
- INTRODUCTION
- BACKGROUND THEORY
- DESIGN / THEORETICAL ANALYSIS
- PROCEDURE
- RESULTS AND DISCUSSION
- CONCLUSION
- WORKS CITED
- APPENDIX
- HOW A READER IN INDUSTRY PERUSES A TECHNICAL REPORT AND WHY YOU SHOULD KNOW..........
- CONCLUSION
- WORKS CITED
- Appendix A – Creating Works Cited Page and Citations within Report
- Citing an Article in a Periodical [1]
- Citing a Book [1]
- Citing Full Text Databases Using APA Format [2]
- Citing World Wide Web Documents [2]
- Creating Parenthetical Citations Using APA Format [3]
- Appendix B – Writing Tips for Results and Discussion Section
- Percent Difference/Error
- Magnitude of Error
- Writing Discussion Based on Lab Questions.....................................................................................
- Guidelines for Graphs
- APPENDIX C – GUIDELINES FOR ANSWERING TECHNICAL QUESTIONS
- Any information in the report that is directly derived or paraphrased from a source must be cited using the proper notation [1, 2, 3].
- Any reference material derived from the web must come from credible and documentable sources. Students need to evaluate websites critically. The first step is to verify a credible author.
- Wikipedia is NOT a credible reference because the information changes over time and authors are not necessarily people with verifiable expertise or credentials.
- For all paper reports, all pages of the report must be 8 ½“ X 11” in size. Any larger pages must be folded so as to fit these dimensions.
REPORT FORMAT
The pages of the report are to be assembled in the following order. This is the recommended order, however, certain reports may lend themselves to either reordering sections and/or excluding sections.
TITLE PAGE
The format for this page may vary, however, the following information is always included: report title, who the report was prepared for, who the report was prepared by, and the date of submission. This is not a numbered page of the report.
ABSTRACT
An abstract is a concise description of the report including its purpose and most important results. An abstract must not be longer than half a page and must not contain figures or make reference to them. The results may be summarized in the abstract but qualitatively, not quantitatively. No specific technical jargon, abbreviations, or acronyms should be used. This is not a numbered page of the report.
TABLE OF CONTENTS
Include all the report sections, subsections, and appendices. This is not a numbered page of the report.
INTRODUCTION
Give the objective of the work, a brief description of the problem, and how it is to be attacked. This section should provide the reader with an overview of why the work was performed, how the work was performed, and the most interesting results. This can usually be accomplished with ease if the work has clearly stated objectives. After introducing the problem, indicate how those objectives are met. The length of this section depends on the purpose but the author should strive for brevity, clarity, and interest. Be careful not to use specific technical jargon or abbreviations such as using the term “oscope” instead of “oscilloscope”. Also, make sure to define any acronyms or abbreviations prior to using them. For example, in a surveying lab report a student might want to refer to the electronic distance measuring (EDM) device. The first time the device is referred to, the student must spell out what the acronym stands for before using the acronym as demonstrated in the previous sentence. This practice should be applied throughout the report when the author wants to use an acronym that has not yet been defined within the report. Do not assume that the reader is familiar with all the acronyms that are familiar to the author.
BACKGROUND THEORY
Include, if necessary, a discussion of relevant background theory. For example, if the phase shift of an RC circuit is to be measured, give the derivation of the theoretical phase shift. Include any preparation specified in the lab manual. In deciding what should or not should be included as background theory, consider presenting any material specific to the lab that you had to learn prior to performing the lab. This section may be divided into subsections if appropriate. Keep the discussion brief and refer the reader to outside sources of information where appropriate. The proper method of providing references and making citations within the report is provided in Appendix A.
DESIGN / THEORETICAL ANALYSIS
Give the details of your design procedure. Be sure to introduce and describe your design work using sentences, equations alone are not sufficient. Use citations if you wish to refer the reader to reference material. Divide this section into subsections where appropriate. For example, a lab design may consist of designing several circuits that are subsequently interconnected; you may choose to treat each circuit design in its own subsection. Keep this section as general as possible, only applying specific numbers after the design is explained. If there is no design but strictly analysis, then provide the important details of all the analysis performed. Be brief. It is not necessary to show every step; sentences can be used to describe the intermediate steps. Furthermore, if there are many steps to the analysis, the reader should be directed to the appendix for complete details.
PROCEDURE
This section varies depending on requirements of the one who assigned the work and the audience. At a minimum, the author discusses the procedure by describing the method used to test a theory, verify a design or conduct a process. Presentation of the procedure may vary significantly for different fields and different audiences, however, for all fields, the author should BE BRIEF and get to the point. Like with any written work, if it is unnecessarily wordy, the reader becomes bored and the author no longer has an audience. Also, the procedure section should never include specific measurements/results, discussion of results, or explanation of possible error sources. Make sure all diagrams provided are numbered, titled, and clearly labeled. Depending on the situation, there are two likely types of procedure sections. In one case, a detailed procedure may have already been supplied or perhaps it is not desirable to provide a detailed description due to proprietary work. In another case, it might be the author’s job to provide all the detail so the work can be duplicated. The latter is more common in academic lab settings. The writing guidelines for each of these possible procedure sections are provided below.
Procedure Type 1
Use this procedure type if you have been supplied with a detailed procedure describing the steps required to complete the work.
- If required by the person who assigned the work, include the detailed procedure in the appendix.
- Briefly describe the method employed to complete the work. This is meant to be a brief description capturing the intention of the work, not the details. The reader must be referred to the appendix for the details. DO NOT refer to procedure steps.
RESULTS AND DISCUSSION
Present the results of the work performed using neatly organized and completely labeled tables and/or graphs whenever possible. When comparative data is available, present the data in a way that facilitates the comparison. For example, if theoretical and experimental values are available, present the values alongside one another accompanied by percent error. If it would help the reader understand the results, include a few sample calculations but put lengthy calculations in an appendix. ALWAYS accompany results with a meaningful discussion. The discussion explains what the results mean and points out trends. In some cases, the results speak mostly for themselves and the discussion may be brief, i.e., “Table 2 shows that the designed variable modulus counter works as expected”. In other cases, the meaning of the results may not be as clear requiring more detailed discussion. ALWAYS discuss the possible sources of error and how accurate the results need to be in order to be meaningful. Do not include a discussion of possible sources of error that would not add significantly to the observed error. What counts as significant depends on the situation. For example, if the components used have a tolerance of 5% and the accuracy of the equipment is within 0.1% of the measured value, then the equipment does not add any significant error. In general, it is impossible to obtain error‐free results, however, attention to detail when conducting procedures should minimize the error. Errors are different from mistakes. It is unacceptable to report mistakes. If a mistake was made in the work, the work must be repeated until acceptable tolerances are achieved before submitting a report. When working in the industry, it is imperative to know how accurate the results need to be. It is worth your time and effort (and in the best interest of your boss or client) to provide the appropriate level of accuracy. If that means repetitive measurements to check for accuracy within tolerance, then do it. If it means performing a detailed analysis prior to making measurements, then do it. In the academic setting, the result of laziness or lack of effort may only be a bad grade. In the workplace, you may get fired! Other information pertaining to writing the Results and Discussion section can be found in Appendix B. This information includes
- How to calculate percent difference/error.
- Typical magnitudes of percent error for courses where circuits are constructed.
- What to consider writing about based on lab questions.
- Guidelines for graphs provided in a report.
CONCLUSION
In this final section of the body of the report, the author should briefly bring everything together. It is similar to the abstract except that now the results are concluded upon in a quantitative way. Therefore, the conclusion should be a concise description of the report including its purpose and most important results providing specific quantitative information. The conclusion should not contain figures or make reference to them. As with the abstract, the reader should be able to read this section on its own which means that there should be no specific technical jargon, abbreviations, or acronyms used.
WORKS CITED
List all works cited in the report, include all the important bibliographical information. The Works Cited should begin on a new page, not on the same page with the conclusion. Refer to Appendix A for information on preparing the Works Cited section.
APPENDIX
This section may not always be present. Materials included in an appendix may include lab sheets, parts list, diagrams, extensive calculations, error analyses, and lengthy computer programs. Introduce numbered appendices rather than putting different items in one appendix.
HOW A READER IN INDUSTRY PERUSES A TECHNICAL REPORT AND WHY YOU SHOULD KNOW..........
SHOULD KNOW
For obvious reasons, the reader will first read the title page and abstract. Therefore, it is imperative that the abstract be clear and well written. It should tease the reader into looking further into the paper. The conclusion is often the next section to be read. All valuable readers, politically speaking, will jump directly to the conclusion making it important to provide a table of contents to ease document navigation. If the conclusion, relative to the title page, sounds interesting and conclusive they will read the other sections to learn more. The introduction is read next. It should provide the reader with enough information about how the report progresses so that the reader can pick and choose which sections are most applicable to their interests. Based on this, some or all of the subsequent sections may be read. In light of understanding how a technical report is read, there are several general guidelines to consider:
- A professional looking and well‐organized document sets the tone for the reader.
- If you use acronyms, describe them first then include the acronym in parenthesis, i.e. Digital Multimeter (DMM). Do not use acronyms in the abstract and conclusion sections.
- DO NOT be judgmental in your writing; “I felt that …”, “the results were great …”, etc. Present the work clearly and validate the work with data accompanied by meaningful discussion.
- Give your report to someone to proofread. Note where they had questions or couldn’t understand your discussion. Then see if you can improve how that information is presented.
- Remember that the reader can’t understand what you are “thinking”. Write your report for a technical peer but do not assume they are comfortable with the current course material.
- Write your reports independent of other reports. Referring to a “Lab 3 Part 1” does not mean anything to a general audience.
CONCLUSION
Technical Report Writing Guidelines provides a recipe for writing technical reports for a variety of disciplines and applications. If all of the information contained herein is studied and applied, the result will be a report worth reading. Considering that most technical jobs require accurate communication through written material, developing good technical writing skills can only improve your career status. Be aware that most jobs in a technical field require a significant amount of technical writing, from informal memos to formal proposals for presentation to customers. It is worth your time to read this material carefully and practice your writing skills.
Appendix A – Creating Works Cited Page and Citations within Report
A tremendous amount of information on proper citing of references in reports as well as how to cite the reference within the body of a report is provided by the College’s Library (see website at http://libraryreference.sunydutchess.edu/citations.htm). For technical reports, the American Psychological Association (APA) method or a modified version as explained below is most often used. For your convenience, this information is provided here, however, it is worth reviewing the website because other valuable resources are provided that facilitate bibliography creation. For technical reports, a modified APA method is often used. Using the APA method, a reference is cited in the body of the report using a “parenthetical citation”. Within the parenthesis, a lot of information is supplied including the author, the publication date, and the page number. If no author is provided, then the title of the referenced work is included. With this technique, a parenthetical citation referencing the information cited here would be ( Creating Parenthetical Citations and Reference List Pages Using APA Format , 2008). In technical reports, an abbreviated method is often used where the reference is identified by the numbered list in the Works Cited section. Using this abbreviated notation, the reference would be just [3]. Square brackets must be used. After the conclusion of a report, if outside sources of information were used a numbered list of the references is provided in the order cited within the paper. Examples of bibliographic information for periodicals and books can be found in [1] and for full text electronic databases and web sites in [2]. The details of how a citation should be written are copied from [1] and [2] here for your convenience. Also provided here is the classic method of providing a parenthetical citation using the APA method [3] in case you opt for that technique rather than the modified method described above.
Citing an Article in a Periodical [1]
When citing an article in a periodical, you must include:
- The author(s) last name(s), followed by a comma, and first initial (s), followed by a period.
- The year of publication and date, in parentheses, followed by a period.
- The article title followed by a period. Capitalize only the first word and any proper nouns (names, places, etc).
- The title of journal, in italics, followed by a comma.
- The volume number in italics.
- The issue number (if available) in parenthesis, followed by comma.
- The pages followed by a period.
Citing a Book [1]
When citing a book, you must include:
- The author(s) last name(s), followed by a comma and first initial (s), followed by a period.
- The year the book was copyrighted in parentheses, followed by a period.
- The title of the book, in italics and followed by a period. Capitalize only the first word and any proper nouns (names, places, etc).
- The place of publication, followed by a colon.
- The publisher followed by a period.
Citing Full Text Databases Using APA Format [2]
When citing an article from a full text database, you must include:
- The author(s) last name(s) first, followed by a comma, and first initial, followed by a period.
- The year of publication in parentheses and date, followed by a period.
- The article title followed by a period. Capitalize only the first word and any proper nouns (names, places, etc).
- Title of the journal, in italics, followed by a comma.
- The volume number (if available) in italics.
- The issue number (if available) in parenthesis, followed by a comma.
- The pages followed by a period.
- The phrase “Retrieved” followed by the date you accessed the article followed by a comma.
- The word “from” and the name of the database followed by a period.
Citing World Wide Web Documents [2]
When citing information that was retrieved from a website, you must include:
- The author(s) last name(s) (if available) followed a comma and first initial.
- The year of publication (if available) in parentheses. If no date is available, use (n.d.)
- The title of the document in italics followed by a period. Capitalize only the first word and any proper nouns (names, places, etc).
- The phrase “Retrieved” followed by the date you found the document on the Web followed by the word “from” and a comma.
- If a government or academic site, the name of the host organization followed by a colon.
- The Web address (URL), followed by a period.
Creating Parenthetical Citations Using APA Format [3]
Parenthetical citations are used to identify the sources you used in writing your paper. These citations appear in an abbreviated form within the text of your paper and lead a reader to the full citations in your Works Cited Page. The standard rule for parenthetical text citations is to include:
- An open parenthesis (
- The author’s last name, if available and not named in the text, followed by a comma
- If no author, the title, in quotation marks
- The date the source was published, if available, followed by a comma
- The page number(s), for direct quotes or if needed to uniquely identify the source, proceeded by “p.” or “pp”. For electronic sources, use ”para” to identify a quote from a specific paragraph
- A close parenthesis )
Guidelines for Graphs
Always refer to graphs and tables when discussing results. Construct graphs using the following guidelines:
- Create the graph using a computer software package such as Microsoft Excel. If computer access is not available, use grid paper.
- Provide one‐inch margins on all sides; do not write in the margins.
- Clearly label axes, including quantity plotted and its units.
- Use a smoothed line to produce the best‐fit curve.
- Clearly indicate data points using a circle, triangle, or square. Use different shapes for different curves plotted on the same axes.
- Label different curves plotted on the same axes.
- Number and title every graph. “Figure 1: V vs. R” is NOT an acceptable title whereas “Figure 1: Measurement of Voltage (V) as a Function of Varying Resistance (R)” is.
- Place all graphs in the report so that the bottom of the graph is either along the bottom of the paper or the right side of the paper.
APPENDIX C – GUIDELINES FOR ANSWERING TECHNICAL QUESTIONS
The list provided below supplies guidelines for answering technical questions as opposed to writing a formal technical report.
- In consideration of the accessibility to word processors, this assignment should be submitted in typed form.
- First type the question, then type the answer.
- If the responsibility of answering the questions is a team responsibility, it is expected that ALL team members contribute to the discussion and writing of the answers.
- Use full sentences and make sure all parts of the question are answered. If asked to explain, make sure to provide adequate explanation.
- Make sure the lab’s objectives are understood as they are the indication of what to focus on in answering questions and writing reports.
- When comparing data, make sure the type of data is clearly indicated. Data that is obtained completely from theory with no use of data collected in the lab is theoretical data. Data obtained from experimental measurements is experimental data. If theory was used to derive data, such as using current to calculate voltage using Ohm’s Law, the result is still experimental in nature since it is based on experimental information. Finally, data can be computer generated or simulated data.
- Tables or graphs should allow for easy comparison between numbers. Indicate the type of data and its units, and supply a percent difference where appropriate. All types of data should be included.
- It is important to be involved in answering lab questions, even if it is a team responsibility. The recommended method of answering lab questions as a team is to organize a team meeting at which the team will discuss and work together to write the answers. If a meeting is not possible, the team should engage in an electronic discussion (possibly using email) to work together to write the responses. Individuals could be assigned to respond to particular questions and then several days before the team report is due, each individual shares their work with the rest of the team. This allows time before the due date for everyone to review and revise the supplied responses.
- When comparing two sets of data, supply the data AND the percent difference. There is little meaning to have one without the other.
- Make sure to read over what you have written to see if it actually answers the question at hand. You may not be getting straight to the point or you may not be backing up your answer with meaningful information. For example, saying that the voltage difference is only 0.02V is meaningless without explaining the percent difference. If the voltage was calculated to be 0.085V and you measured 0.065V then the percent difference would be –31%! Whereas if you measured 0.58V and you expected 0.6V, then the percent difference is only 3.4%. Both cases are for a 0.02V difference … do YOU see the difference?
