How to Organize Technical Reports People read technical reports to get good information as quickly as possible. They are not reading for pleasure. After reading the first paragraph (or page, for a long report), I should know whether the report contains the information I need. Then, I should be able to find that information without reading the whole report. Golden Rule of Organizing Technical Writing: No surprises for the reader. Briefly summarize the most important points, then give the details. Organize each paragraph, each section, and the report as a whole this way. Your first, rough draft will typically be organized VERY differently from your final product. Your rough draft is organized to be easy for you. o First, get the information down, then organize it properly later. o Write things in the order that you did them (chronological, like a diary). o Or, write down the details, and then write down what you think they mean. Your final report is organized to be easy for your reader. o Organize each paragraph so that the key information is stated first, followed by supporting details. o Organize each section so that the key information is stated first, followed by supporting details. o Organize the report as a whole so that the key information is stated first, followed by supporting details. o The first paragraph of the report is the last thing that you write. If you ever submit a “draft” for review by your boss, it should not be a first, rough draft. It should already be organized as if it is the final report. It may be missing the up-front summary paragraph. It may have some missing values or figures. It may have some questions still to be answered or information still to be verified. But nothing that reads like a data dump or a mystery novel should ever go to your boss, or to your professor. The First Paragraph: 1 – 2 sentences, brief but specific, on the following topics. What is the problem? What are the key features of the solution(s) presented? What do you recommend, or what still needs to be done? What is not part of this report? (optional) Sections and Headings Any technical report longer than one page should have sections with headings. Even a 1-page report can benefit from sections with headings. Good technical writing requires a significant investment of time. You probably thought that developing technical solutions would be hard work. Communicating them is hard work, too. Do not waste a good technical solution by communicating poorly. Organization–OhioUniversityChBE–UpdatedSpring2015 Page1/1 Writing a Memo Format A memo starts with a “header”. A typical header is . . . . . To: the names and titles of people who need to act From: the names and titles of the members of your team Date: the date that you send the memo to the people in “To” Subject: a brief, specific description of the memo’s scope cc: the names of people who should be informed, but don’t need to act. Could be “file”, meaning that a record should be kept. “cc” means “carbon copy”. You may sign a memo, or initial next to your name, or use your “signature block” if it is the body of an e-mail. Send the memo to everyone in the header simultaneously. Purpose and Audience An engineer’s memo is a short technical report. It is both a report of the current situation and a record for the future. Typically, the purpose of a memo is: (1) To report progress, or . . . (2) To report a result or decision, or . . . (3) To request a decision. The audience for an entry-level engineer’s memo is typically: (1) Your boss (probably technically-educated, maybe not ChE, overseeing multiple projects so remind her which one you are discussing), and . . . (2) Your boss’s boss (maybe technically-educated, providing high-level oversight of multiple projects, will probably read only the first paragraph), and . . . (3) Another engineer (technically-educated, maybe not ChE, needs to know whether what you did is relevant to his/her current problem, may not be able to talk directly to you). Organization Begin with an Action Paragraph o Identify the problem or situation o State what you want your reader to do. Be informed. Decide among options or authorize an action. Act. o Summarize the most important information that your reader needs. What did you observe or learn? What do you recommend? After the Action Paragraph / Sentence, provide the additional detail that a reader could use to fully understand the situation. If the memo is more than one page, divide it into sections with headings, so that your reader can easily locate information. Tip Write an informative “Subject”. Neither “Assignment 4” nor “Condenser Project” is sufficient. Memos–OhioUniversityChBE–UpdatedSpring2015 Page1/1 Agendas Meet only for tasks that are most effectively done as a team. For example, everyone does not need to search the literature together. However, it is effective to meet to brainstorm key words for searches or key questions that should be answered. Between meetings, teammates can share information electronically. (Use Google Drive, Dropbox, e-mail, text.) Allow about 5 minutes for informal conversation before starting business. This helps satisfy teammembers who value interpersonal relationships, without frustrating those who prefer to complete the required tasks before socializing An agenda for a team meeting should include: 1. The proposed start time and end time and the location. a. Ideally, set a target time to spend on each agenda item. b. Keep it short, under an hour. Much work should be done by subgroups. 2. A deliverable that each person should bring to or present at the meeting. a. Deliverables encourage progress between meetings, so meetings are more productive. b. Sample pre-meeting deliverables are i. A proposal for how to divide the project workload. ii. A list of questions not yet answered from the literature. iii. A completed ChemCAD simulation. iv. A proposal for dealing with a team member who is not contributing. 3. Deliverables to be achieved during the meeting. a. Stating deliverables rather than topics helps the team make progress. b. Sample meeting deliverables are i. A consensus timeline for completing the project. ii. A list of key words for the literature search. iii. A preliminary design sketch. iv. Agreement on what action to take about a team member who is not contributing. 4. Time to discuss the agenda for the next meeting. a. Choose a preliminary time and place. b. Assign each team member a deliverable for the next meeting. c. Assign a person to e-mail the draft agenda to everyone for comment. Agendas–OhioUniversityChBE–UpdatedSpring2015 Page1/1 Including Equations in Technical Writing A Good Example The “gain”, K, describes the sensitivity of a process variable to a change in the process operating conditions. For example, if the flow rate of steam in a process is controlled by the position of a valve, then the gain of the valve is defined by Equation 1.1 K = ∂m / ∂x (1) Here, K (kg s-1 %-1) is the gain of the valve, m (kg s-1) is the mass flow rate of steam, and x (%) is the position of the valve, which is described as “per cent open”. When x = 0 %, the valve is “0 % open”, or completely closed. When x = 100 %, the valve is “100 % open”. The gain may be a constant under some conditions, but it is risky to assume constant gain without evidence. It is not unusual for K to depend on x. Points to Remember Always think about the convenience of your reader. Only show equations which will help your reader understand your work more clearly. Do not show every step of your solution in the main part of your report. You might show a step-by-step solution as an appendix, if you think it would be useful for reference. Place each equation on a separate line, with a number to identify it in parentheses well to the right so it is clearly not part of the equation. The first equation that appears in the paper is Equation 1. The next is Equation 2. You might also number them to identify the section where they are introduced. For example, the third equation in section 1 of a paper could be numbered 1.3. Introduce each equation in the text, referring to it by number (e.g. “… is defined by Equation 1.”). To discuss the same equation again later in the paper, refer to it by number. Do not repeat the equation unless it has been a couple of chapters since it was last used. If you repeat an equation, keep the same identifying number. Define every symbol in each equation immediately after the equation. If there are many symbols, you can make a list instead of using sentence format. Include units. After you define a symbol, do not change it. If you use equations from different sources, make the symbols consistent in your paper. For example, I have a book1 which includes Equation 1, but it uses F as the symbol for mass flow rate. I changed the symbol to m, to be consistent with my usual symbols. Note any assumptions which are important for using an equation. For example, if you present the Bernoulli Equation, note that its use is limited to incompressible fluids. 1 Smith, Cecil L. Practical Process Control: Tuning and Troubleshooting, p. 29, Wiley, 2009. Equations–OhioUniversityChBE–UpdatedSpring2015 Page1/1 Including Figures in Technical Writing A Good Example Figure 1 shows a typical temperature control system for a jacketed reactor. The distributed control system receives the temperatures of the reactor and the cooling water inlet and outlet from temperature transmitters (TT), and the volumetric flow rate of the cooling water from the flow transmitter (FT). The signal for the reactor temperature is provided to the temperature controller, which adjusts the position of the cooling water return valve to try to maintain the desired reactor temperature. The reactor temperature is the “controlled variable”; the position of the cooling water return valve is the “manipulated variable”. Treactor TT TC TT T Cooling Water Return CW,out TCW,in TT FT VCW,in Cooling Water Supply Figure 1. Temperature control configuration for a vessel with a cooling jacket. [Adapted from Cecil B. Smith, Practical Process Control: Tuning and Troubleshooting, Wiley, 2009, p. 58] The simple schematic in Figure 1 shows some important features in control system design that improve safety and enable trouble-shooting. (1)In addition to the controlled and the manipulated variables, other related process variables are monitored. For example, if the cooling water return valve is fully-open, but the reactor temperature is still too high, the operator can determine whether the cooling water inlet temperature may be too high, or the cooling water supply flow rate may be too low. These additional process variables may be linked to alarms. (2)The reactor temperature measurement is placed so that even when the liquid level is low, the measurement device will still be immersed. (It is also important to monitor the liquid level in the reactor, but that system is not shown, because this diagram focuses on temperature control.) (3)The cooling water enters at the bottom of the jacket, and the control valve is on the outlet at the top, so that the jacket will be full of water even if the control valve closes. Figures–OhioUniversityChBE–UpdatedSpring2015 Page1/2 Points to Remember Figures may be diagrams, photos, graphs or plots. Tables are not figures. Include only figures which will help your reader. Figures which are discussed in the body of the memo / report belong in the body of the memo/report. Figures which are for reference / documentation only belong in an appendix. Try to simplify the figure to make important features obvious. For example, it is easier to understand how something is constructed from a diagram than from a photograph. Number each figure. The first figure in the document is Figure 1; the next is Figure 2. You may number them to identify the section where they are displayed. For example, the third figure in Section 1 of a paper could be Figure 1.3. Place the figure number and the figure title and/or caption underneath the figure. o Title: a few words to describe the figure. Do not simply repeat the axis labels. o Caption: one or more phrases or sentences to explain the figure (point out important features, define symbols, provide additional information). o Title, caption, or both? Consider (1) what your reader needs to gain a basic understanding of the figure, and (2) the format expectations for the document. Figures have the same margins as the rest of the document. Discuss each figure in the text, referring to it by number (e.g. “… is shown in Figure 1.”). Explain the meaning and importance of the figure in the text. Figures reproduced from another document (even yours) must have the notation “Reproduced from:” and the complete reference in the title/caption. Typically, for external publication, you also need the permission of the original publisher. Often, for school assignments and internal informational documents, publisher permission is not needed to reproduce a single figure from a larger document. For a concise description of “Fair Use”, see http://www.nolo.com/legal-encyclopedia/fair-use-rule-copyrightmaterial-30100.html. Only reproduce a figure to critique or analyze the original figure. To illustrate a concept in your own work, make a similar figure that contains features specific to your work. See below. Figures which are based significantly on a figure from another document (even yours), but drawn by you and altered to be specific to your document must have the notation “Adapted from” and the complete reference in the caption. Typically, permission from the original publisher is not needed to adapt a figure. This is generally a better choice than reproducing a figure. Figures–OhioUniversityChBE–UpdatedSpring2015 Page2/2 Including Graphs (Scatter Plots) in Technical Writing A Good Example Figure 1 shows both predicted and experimentally measured responses of Dependent Variable on imposed changes in Independent Variable. The predicted changes in Dependent Variable are made based on the theoretical relationship described in Equation 1, below. DV = 2(IV) (1) where DV is the Dependent Variable (units) and IV is the Independent Variable (units). Figure 1 confirms that Equation 1 provides an acceptable way to predict the DV-to-IV relationship. Dependent Variable (units) 20 15 10 5 Experimental Data Model (Equation 1) 0 0 2 4 6 8 10 Independent Variable (units) Figure 1. The impact of changing Independent Variable on the response for Dependent Variable. Data points represent experimental measurements; the model line is described by Equation 1. Figures(Graphs)–OhioUniversityChBE–UpdatedSpring2015 Page1/2 Points to Remember Use graphs to visually communicate the relationships between two or more variables to your reader. All rules in the “Including Figures in Technical Writing” document also apply to graphs. You are the boss of the graph!! Do not let Bill Gates and Excel dictate your graph formatting. You can control most, if not all, features of the graph. Do not accept default formatting in any software unless it provides the clarity that your reader expects. More Points to Remember for Graphs Use the x-axis for the independent variable and the y-axis for the dependent variable. Select the limits of the graph (maximum and minimum values that will be shown for the independent and dependent variables) so that your experimental points and/or model lines take up most of the graph area. The “origin” point on the graph does not have to represent zero on either axis unless you have data or interest in this region. Label your axes and include units with your labels. Divide your axes so that tick-mark labels are logical and easy to read. Only include grid lines if they aid in either understanding or using your graph. Represent data using symbols; error bars may be appropriate. Represent model or equation results by a smooth, solid or dashed line with no symbols. There are very few valid reasons for a “connect the dots” graph. Include a legend within the graph if it will help the reader to understand the graph. As an alternative, you might include the legend information in your Title/Caption. (A legend that says “Series 1 . . . Series 2” is neither helpful nor desired.) For graphs included in a document, the Title/Caption under the graph is the graph title. A second title within the graph is neither necessary nor desired. Make the graph large enough to read. At least ½-page is an appropriate size. [Trick of the trade – Be careful when using color in your graph! Blue square symbols and black square symbols may both look black (and yellow symbols may disappear altogether) if your graph is reproduced on a black-and-white copier. You need to ask yourself if your color graph would still make sense to a reader if it were copied in black-and-white. If your answer is “no” you should change your graph so that your answer would be “yes.”] Figures(Graphs)–OhioUniversityChBE–UpdatedSpring2015 Page2/2 Including Tables in Technical Writing A Good Example The expression used to describe the heat capacity at constant pressure (Cp, kJ mol-1 C-1) is Cp = a + bT + cT2 + dT3 (1) In Equation 1, T (C) is the temperature and a, b, c, and d are empirical constants whose values for acetone and n-hexane are given in Table 1. Table 1. Coefficients for the Calculation of Heat Capacity at Constant Pressure1,2 Acetone n-Hexane liquid Vapor liquid vapor 3 -1 -1 123.00 71.96 216.30 137.44 a × 10 kJ mol C 18.60 20.10 40.85 b × 105 kJ mol-1 C-2 8 -1 -3 c × 10 kJ mol C 12.78 23.92 12 -1 -4 34.76 57.66 d × 10 kJ mol C 1 Cp = aT + bT + cT2 + dT3 2 Values are from Table B.2, R.M. Felder and R.W. Rousseau, Elementary Principles of Chemical Processes, 3rd Edition, John Wiley & Sons, Inc., 2000. Points to Remember Use a table when you want the reader to have particular values. Plots are more effective to show trends or make comparisons. Put the table number and title at the top of the table. Give column and each row a heading. Use horizontal lines only at the top and bottom of the table, and to divide the headings from the entries. Very rarely, you might use one or two vertical lines to divide a table into sections. Do not draw lines like a grid for a memo / report. On a presentation slide, a grid format might be appropriate Units are required. Typically, units are best displayed in the row and/or column heading. Display values with a consistent number of places beyond the decimal point, and rightjustify them so that the decimal points line up. Use multipliers in column / row headings to make values easier to read. o a × 103 means that the entry has been multiplied by 103. So, for acetone liquid in Table 1, the value of a is 0.123 kJ mol-1 C-1. o The row heading could alternatively be written “a, 10-3 kJ mol-1 C-1” Zero entries make a table look cluttered; use a short dash instead. Refer to the table by number in the text. Tables–OhioUniversityChBE–UpdatedSpring2015 Page1/1 1 Comment [YV1]: Step‐by‐step calculations belong in the appendix. A summary of the key assumptions and principles that you used to solve the problem belongs in the body of the memo / report. Appendix – Detailed Calculations 150 , 150oC = 423 K, 1.5 atm o ( (kW) ) y1 ( yo ( (1‐yo )( ) (1‐y1 )( Comment [YV3]: Symbols in the appendix and in the body of the memo / report should be the same. , 0‐80oC, 5 atm Comment [YV4]: Use conventional symbols, for example, y is conventionally a mass or mole fraction. o = [(1.5 atm)(150 Comment [YV2]: Symbols used and quantities known are defined (with units) in this diagram , 0‐80oC, 5 atm 1 ( )] / [(0.08206 s =‐30kW 423 K)] = 6.48 2 ( ; *Ideal Gas Law Comment [YV5]: The source of every number should be obvious. Each number should be from the literature, given or measured for this problem, or from a previously‐shown calculation. The values in this equation are the Ideal Gas Constant (which any chemical engineer would recognize) and values already specified in the diagram above. A 3.00 L sample was analyzed to determine the feed stream composition. yo = [(1.111 g Benzene)(1 mol Benzene / 78.11 g)] / [(3.00 L)(1.5 atm) / (0.08206 yo = 0.110 (1‐yo ) = 1‐0.110 = 0.890 (0.110 (0.890 (423 K)] Comment [YV6]: Include notes to identify assumptions and standard equations. ) = 7.13 ) = 5.77 log10 (p*Benzene (50oC)) = 6.89272 – 1203.531 / (50+219.888) = 2.4333 o p*Benzene (50 C) = 271.2 mmHg = 0.3569 atm y1 = [p*Benzene (50oC)] / (5 atm) = 0.0714 (1‐y1 ) = 1‐ 0.0714 = 0.929 )( 6.48 )( 6.48 * Antoine Equation * 760 mmHg / 1 atm * Raoult’s Law Air Balance: 1 = [(6.48 Comment [YV8]: Include notes and headings to explain your thinking. (0.890 Benzene Balance: 2 = (6.48 Comment [YV7]: It would be even better to note the source for these Antoine coefficients. (0.110 )] / (0.929 ) – (6.21 ) = 6.21 )(0.0713 ) = 0.269 DetailedorSampleCalculations–OhioUniversityChBE–UpdatedSpring2015 Page1/2 2 Reference: C6H6(l, 50oC, 5 atm); Air(g, 25oC, 1 atm) in(Air) = 3.67 out(Air) = 0.73 *Interpolation Table B.8 *Interpolation Table B.8 + ∆ in(Benzene) = out(Benzene) = = s + ∑ ‐ ∑ + ∆ + ∆P = 42.6 v + v + = 32.2 = ‐30kW + [(5.77)(0.73)+(0.443)(32.2)+(0.269)(0)] – [(5.77)(3.67)+(0.713)(42.6)] = ‐63.1 kW Substance in( Air Benzene(v) Benzene(l) 5.77 0.713 in ( 3.67 42.6 out ( 5.77 0.443 0.269 out ( 0.73 32.2 0 DetailedorSampleCalculations–OhioUniversityChBE–UpdatedSpring2015 Page2/2 Writing About Your Calculations In the body of your memo / report, you should write about how you solved the problem. A stepby-step account of the solution belongs in an appendix. Only one of the examples below belongs in your technical writing at all. Example 1 First, I calculated n0 by multiplying the inlet pressure by the inlet flow rate and dividing by the gas constant and the absolute temperature. I got the absolute temperature by adding 273 to T0 in ºC Then I needed to know the mole fraction of benzene in the feed stream. I calculated y0 by multiplying 1.111 g of benzene by the molecular weight of benzene (78.11 g/mol), and then dividing by the moles in the 3.00 L gas sample which I got by multiplying 3.00 L by 1.5 atm and dividing by the gas constant and the absolute temperature. After that, I needed to know the composition of the gas coming out, so I found the vapor pressure using the Antoine Equation for benzene, and then divided by the outlet pressure of 5 atm to get y1. Then I calculated all of the flow rates. n2 was 0.269 mol/s. After that, I integrated Cp values to find specific enthalpies, except that for some streams I also included the heat of vaporization. Q is -63.1 kW when T is 50 ºC. I did all of the calculations with my calculator. Example 2 Step-by-step calculations of the liquid benzene recovered and the heat transfer required are shown in the appendix, using an exit temperature of 50 ºC for the condenser unit. At 50 ºC, I estimated a benzene liquid recovery of 0.269 mol/s (3.77 %) and a required heat transfer rate of 63.1 kW from the process stream. The inlet stream to the condenser contains 0.110 mol benzene / mol, based on analysis of a 3.0 L sample of the inlet gas. To determine the liquid benzene recovered and the heat transfer required, I assumed steady state operation, no heat exchange with the environment, and that the vapor and liquid streams leaving the condenser unit were in equilibrium with one another. I used Raoult’s Law to model vaporliquid equilibrium, assumed that air was non-condensable, and assumed that any liquid condensed was pure benzene. I estimated the vapor pressure of benzene using the Antoine equation with the constants in Table B.4 of Felder and Rousseau’s text. To convert between volumetric flow rates and molar flow rates, I assumed that gases and vapors behave ideally. I obtained heats of vaporization from Table B.1 and heat capacities at constant pressure from Table 2 in Felder and Rousseau’s text. WritingAboutCalculations–OhioUniversityChBE‐UpdatedSpring2015 Page1/2 Example 1 is a problem because . . . . The reader does not know what you are trying to calculate. It is difficult to understand a procedure when you do not know the objective. You restate mathematical equations as text, a confusing format which provides no additional insight. You use symbols instead of clear descriptive nouns, which hopefully are defined in a nearby figure or list, but the reader is still inconvenienced and possibly confused. You do not clearly state your assumptions or identify your sources of information, so your reader cannot evaluate their reasonableness. You distract the reader with an inconsistent level of detail. You explain unnecessarily how you perform routine calculations. You should identify the software for complex modeling when the result is likely to be different if different software is used. Routine calculations are the same with any tool (calculator, Excel, slide rule, abacus). In general, the real world is described by positive real numbers. A negative sign in chemical engineering is a convention used in calculations to indicate direction, but when you write you should usually use real positive numbers and indicate direction with words. There should be no negative heat transfer or negative flow rates in a memo. Example 2 is good because . . . . You begin by telling the reader the objective of the calculations and the key results. You notify the reader that a step-by-step appendix is available, but don’t force the reader to sit through it. You provide higher-level insight that may not be obvious from the equations in the stepby-step appendix. For example, the assumption that the outlet streams are in equilibrium with one another is critical, but may be obscured by the details in the appendix. You use clear descriptive nouns. You clearly state your assumptions and identify your sources of information, so your reader can evaluate their reasonableness. You provide a consistent level of detail. You use positive real numbers and indicate direction in the text. WritingAboutCalculations–OhioUniversityChBE‐UpdatedSpring2015 Page2/2 Discussion of Results When discussing results, your figures, tables, and text should work together to explain your observations to the reader. Do not leave the interpretation to the reader. Consider these two explanations of Figure 1. Example 1 There is a red dashed line and a blue solid line on the figure below, representing heat transferred and acetone recovered, respectively. Both lines go down with temperature. The liquid acetone is zero above 48 ºC Example 2 The liquid acetone recovered and the required heat transfer by the condenser are represented in Figure 1. Both acetone recovered and heat transfered decrease as the exit temperature from the condenser unit increases. The dew point of the inlet stream is 48 ºC at the condenser unit operating pressure; no liquid acetone can be recovered above this temperature. There is also a discontinuity in the heat transfer curve at 48 ºC, because no condensation occurs at higher temperatures. 90 0.9 70 Heat Transferred, kW 0.8 Heat Transferred, kW Acetone Recovered, mol/s 0.7 60 0.6 50 0.5 40 0.4 30 0.3 20 0.2 10 0.1 0 Acetone Recovered, mol/s 80 0 0 10 20 30 40 Temperature, °C 50 60 Figure 1. Partial condenser operating parameters. Increasing exit temperature results in less heat transfer required, and less acetone recovered. No liquid acetone is recovered above 48 ºC. WritingAboutYourResults–OhioUniversityChBE–UpdatedSpring2015 Page1/2 Example 1 is a problem because . . . . You refer to “the figure below”, which is vague. Instead, refer to figures, equations, and tables by number, so that the reader knows exactly which one you mean. You describe the plot like it’s abstract art. Instead, you need to describe what the plot represents in the physical world. Example 2 is good because . . . You refer to Figure 1, so the reader knows exactly which figure you mean, and the reader also knows that there is a figure that might provide insight. You describe the physical meaning of the lines depicted on the plot. WritingAboutYourResults–OhioUniversityChBE–UpdatedSpring2015 Page2/2 Write Concisely “Engineering writing should be concise. A sentence contains no unnecessary words. A paragraph contains no unnecessary sentences. A drawing contains no unnecessary lines.” –John X. Wang, What Every Engineer Should Know About Business Communication, CRC Press, 2008. Technical writing should use correct technical terms with common, everyday words to complete the sentence. Leave your thesaurus on the shelf. Examples: accomplish do, complete utilize use ascertain determine endeavor try very Use simple sentences. Avoid wordy expressions and redundant words. Examples: It would appear that one or more individuals have . . . It appears that someone . . . In view of the fact that benzene’s vapor pressure surpasses that of the remaining components concomitant in the mixture . . . Because benzene has the highest vapor pressure in the mixture . . . Use a strong and specific verb instead of a weak, vague verb and a bunch of nouns. Examples: We held a meeting to discuss consideration . . . We met to discuss . . . She made the decision to give her approval to . . . She approved . . . Be as precise as you can. Don’t use “many” or “few” if you have a number. BeConcise–OhioUniversityChBE–UpdatedSpring2015 Page1/1