Technical Writing

Some resources

• Word and LaTeX report template — Please start your report from one of these templates
• A sample technical paper with comments
• Another one
• NIST/APS Guide for Metric Practice
• http://physics.nist.gov/cuu/Units/checklist.html
• Peer Review Form (.doc)
• Peer Review Form (.pages)
• Peer Review Form (.pdf)

Technical Report

One of your requirements for What Makes Things Tick? is writing a technical report. There is no page limitation but you should restrict yourself to 1500–2500 words. This allows your report to be complete and informative, but also requires concision. Please start your paper from one of the templates in the archive you can download here, and endeavor to respect the formatting conventions it contains. The template files—which have a number of helpful suggestions and examples—will streamline the writing process somewhat. However, it is only fair to point out that real research papers go through many, many drafts before being submitted for publication—often dozens. It is not easy to write clearly and concisely for most mortals, and so we write and rewrite and rewrite...

Learning to produce a good technical paper takes time, and for that reason you will be given several opportunities (groan) at HMC to improve your technical writing. We know from alumni surveys that the great majority of Harvey Mudd alumni have found that writing skills were much more important to their careers than they anticipated, and that they wish they had worked harder on writing while in college. Save your reports after they are returned to you to serve as models for future reports.

Goals

Your purposes are:

• to entice the reader to continue beyond your title and abstract to read the entire paper;
• to provide appropriate technical background to motivate the experiment you conducted;
• to explain clearly the relevant procedural issues and results;
• to summarize key experimental findings in figures (and occasionally in tables);
• and to provide conclusions of your findings that are as quantitative as possible.

Strategy

Figure 1 – Angle of incidence {$\theta$} (in acrylic) vs. angle of refraction {$\phi$} (in air) at {$\lambda = 632.8~\textrm{nm} $}. The smooth curve is a weighted least-squares fit to the equation {$\theta = \arcsin(\frac{\sin\phi }{ n})$}, for which {$\tilde{\chi}^{2} = 1.0$}. The fitted value of {$n$} is {$1.xxx \pm 0.002$}. [I get to hide my value, but you don't!].

Although it is tempting to begin writing before you have finished analyzing your results, don't. The linchpin of a physics paper is the graph (or graphs) that summarize your principal results. Frequently, this graph displays a comparison of experimental data and a theoretical curve, with a panel of residuals showing the discrepancy between the two. An example is shown in Fig. 1. Until you have prepared this graph, you don't have a story to tell. So prepare the graph first.

If you have questions about your analysis, and how to prepare this graph, speak to your professor—early! When it's ready, bring him or her a copy of the graph to discuss it and to make sure that your analysis is sound.

With the revised figure in hand, you have the focus of your paper. Everything that appears in your paper before this figure leads up to the figure; everything that appears after it discusses its significance. Hold this notion firmly in mind as we review the sections of the paper.

Elements of a technical paper

Sections

The organization of a technical report follows a formulaic pattern, which is illustrated in table of the previous section. The elements of the paper are listed in the order in which they appear in the paper, not the order in which you should write them! Although the abstract appears third on the list, you should probably leave it to the very last. Abstracts must be extremely concise and they can be a challenge to write. It is better to build momentum by writing some of the easier sections first.

Theory

Assuming that you have completed the analysis of your data, and that you have prepared the figure(s) that summarize your results, I recommend beginning with the theory section. Your section should be self contained; it should not rely on the course manual or other external sources, although it may make reference to external sources. Write for an educated person who understands mathematics and who has some science background, but who has not conducted the experiment you did and is unfamiliar with the equipment you used. The theory section should acquaint or remind your audience of the crucial theoretical background to your experiment, without attempting to fill in all the steps. Make sure to define all symbols you employ, and to explain the mathematics in plain English. Omit steps in a derivation that are merely algebraic manipulations.

Number equations so that you can refer to them later in the text. Remember that variables are set in italics {$x$}, but functions and numbers are set in Roman (upright) font:

If you are using Microsoft Word, please avoid the built-in equation editor. The school has a site license for MathType, which you may install on your own computer. MathType equations play nice across platforms, whereas Microsoft’s formats don’t.

Experiment

In writing this section you should have in mind a reader who has your background in physics and is familiar with typical laboratory apparatus, but has no knowledge of the specific experiment you are describing and probably has no intention of repeating it. Therefore, you should describe your experimental apparatus and the procedures you followed only insofar as it is necessary for him or her to understand how you made your measurements. A careful drawing of the apparatus is often useful here.

In this regard it is important for you to understand the distinction between a technical report and a laboratory manual. The latter is designed primarily to give instructions on how an experiment is to be carried out, while the former describes to the reader what the author has done. Though it is sometimes necessary in a technical report to describe the procedures that were followed in carrying out the experiment, such material should be kept to a minimum, and under no circumstances should it instruct the reader as though he or she were a student in a laboratory.

Data and Results

State first (or show first) your data before providing an interpretation. If you averaged 10 measurements of the pendulum period, simply state that the average of 10 measurements was 1.87 s, with a standard error of 0.08 s. You may also report this result as {$ (1.87 \pm 0.08)~\textrm{s} $}. Note that standard error and standard deviation of the mean are synonyms.

Usually, you will present your data in graphical form, as in Fig. 1. Occasionally, a table is more appropriate. However, do not display raw data in a table.

Figures and tables must be introduced and discussed in the text; they cannot be placed “inline” with the text, and they certainly cannot be used to begin a section. Figure 1 above shows an example. Notice how the figure is referenced from the text. See the sample papers linked at the top of this page for further illustrations of how to include figures.

Some form of error analysis should be included with your results, and the uncertainty of the final result should be stated clearly. The analysis of errors must be thorough and convincing. Your goal should be to persuade a skeptical reader that your quantitative results are believable. This will often require a more thorough analysis of experimental errors than was done in your lab notebook.

Discussion and Conclusions

This section will often contain further analysis and discussion of your results in order to support and clarify your conclusions. Your final conclusions should be quantitative, precise, and specific, but they should not be simply a summary of the experimental results. Rather, they should be convictions arrived at on the basis of evidence previously presented and analyzed.

Until this section, the paper has grown progressively narrow, beginning with a broad introduction and tapering down to the nitty-gritty of your actual experiment. Once you have presented your most careful analysis, it is time to open up the discussion again, placing your work in a broader context. Make sure that you fulfill any promise you make to the reader in the Introduction as to what your paper would demonstrate or prove. You may want to include suggestions for further work.

Introduction

The Introduction needs to apprise the reader quickly of the topic and scope of the paper, to engage the reader, and to persuade her or him to continue reading. It may be the most challenging part of the paper to write. The first paragraph of the Introduction is particularly critical, since it plays a major role in determining the reader's attitude toward the paper as a whole. You will probably need to rewrite this section more than other sections.

• Make the precise subject of the paper clear relatively early in the Introduction. You should assume your reader is someone with essentially your background in physics but with no particular knowledge of the experiment you performed. Thus you should include background material only to the extent necessary for the reader to understand your statement of the subject of the paper and to appreciate the scientific reasons for your doing the experiment to be described.
• State the purpose of the paper clearly. This statement should orient the reader with respect to the point of view and emphasis of the report and what he should expect to learn from it. A well-done Introduction will also be of great help to you in providing a focus for your writing and in drawing your final conclusions (see below).
• Indicate the scope of the paper's coverage of the subject. State somewhere in the introductory paragraphs the limits within which you treat the subject. This definition of scope may include such topics as whether the work described was experimental or theoretical (In this particular case, the work is almost certainly experimental), the exact aspects of the general subject covered by the paper, the ranges of parameters explored, etc.

An example is given below in the section on passive voice.

Abstract

The abstract should be a concise and specific summary of the entire paper. It should be as quantitative as possible and include important results and conclusions. Including all this in fewer than 100 words takes careful thought (and probably considerable rewriting). An example:

The speed at which light propagates through air at room temperature and atmospheric pressure was studied using a time-of-flight technique. A value of {$ (2.995 \pm 0.003) \times 10^{8}~\mathrm{m/s} $} was obtained, with the dominant error arising from the bandwidth of the oscilloscope used to observe the light pulses. This value is consistent with literature values for {$ c $} and the refractive index of air.

References

Oy vey! Reference formatting is one of the dumbest things in technical writing. Your paper should have references to published literature, where appropriate, but the format of those references as they appear in standard physics journals exhibits a remarkable (and pointless) variety. Every journal seems to have its own preferred way of doing things. Physical Review uses one style, except for Physical Review B, which uses a different one. Neither includes article titles, although IEEE style does. Physical Review used to put references at the bottom of the page; now they appear as endnotes and all you see in the body of the text is a number in brackets (or a superscripted number, in Phys. Rev. B). Neither approach is as civilized and useful as an (author, date, page) in-text citation style, which is sadly uncommon in physics publishing. (Bibliographic database software, such as Endnote or ProCite, can simplify the task of reference formatting, but is apt to be overkill for the technical report. These programs understand the styles of a vast number of publications, and can format the bibliographic information in their databases to match the requirements of whichever publication you target. You can also store notes and other information associated with references in your bibliography, and reuse this information in multiple publications. For extended research projects, such software can be extremely convenient.)

Unless your professor tells you otherwise, you may use either numbers or (author, date, page) citations in the text of your report. No matter what the format, though, the complete reference must appear in the list of references at the end. If you use a numeric style, subsequent references to the same source should use the same number, and the list of references should appear in the order of first citation. For the (author, date, page) format, alphabetize the references by author.

• No item should appear in the list of references without specific citation within the body of the text.
• Cite published and commonly available sources (not the lab manual).

In the References section at the end of the paper, include the complete bibliographic information for each of the cited works. Following is a list of references styles that roughly follow the American Institute of Physics Style Manual. Note that the titles of majors works are italicized, and volume numbers are set in boldface.

1. (journal article) Gale Young and R .E. Funderlic, J. Appl. Phys. 44 (1973) 5151.
2. (translated journal article) V. I. Kozub, Fiz. Tekh. Poluprovodn. 9 (1975) 2284 [Sov. Phys. Semicond. 9 (1976) 1479].
3. (book) L. S. Birks, Electron Probe Microanalysis, 2nd ed. (Wiley, New York, 1971), p. 40.
4. (book section) D. K. Edwards, in Proceedings of the 1972 Heat Transfer and Fluid Mechanics Institute, Edited by Raymond B. Landis and Gary J. Hordemann (Stanford University, Stanford, CA, 1972), pp. 71-72.
5. R. C. Mikkelson (private communication).
6. James B. Danda, Ph.D. thesis, Harvard University, 1965.

Passive Voice

In The Elements of Style, Strunk and White suggest using the active voice as much as possible. This is a worthy goal in scientific writing, but often the role of the investigator is irrelevant to the topic at hand. Because the passive voice emphasizes the phenomenon not the investigator, it is frequently more appropriate in scientific writing. Compare the following introductory paragraphs, the first taken from a student’s technical report, and the second a rewritten version:

By running a current through a coil of wire, we can produce a magnetic field which will deflect the needle of a compass. When we have done this, we can take a bar magnet and position it such that the needle is no longer deflected. Once this has been done, we need only to measure the distance from the needle’s center to the magnet. Using this and the properties we have already measured from the magnet and the coils, we can calculate the current through the loop. Because we only took measurements of mass, length, and time we have determined a value for current not based on any other electrical or magnetic quantities. [Emphasis added.]

Revision:

Hans Christian Oersted discovered in 1820 that a current flowing in a wire generates a magnetic field proportional to the current.¹ By comparing this field to that produced by a calibrated permanent magnet, and by using a geometry in which the constant of proportionality between field and current can be readily calculated, it is possible to measure the current—an electrical quantity—by measuring only the mechanical quantities mass, length, and time. C. F. Gauss first proposed a technique for making such an absolute determination of current in 1823.² We report here a modification of his technique which yields current measurements having an accuracy of 1%.

In my opinion, the use of the first person in the first paragraph does not add useful information; rather, it detracts from the message that these phenomena exist independent of the observer. The second paragraph uses some active voice and some passive voice, throws in some historical information, and keeps the discussion conceptual, as befits an introduction.

Make no mistake: good writing of any kind, whether technical or not, requires practice and a willingness to rewrite. Simply put, it’s hard!

Do’s and Don’t’s

Do’s

1. Divide the report into clearly labeled sections (Abstract, Introduction, Theory, \ldots).
2. Number all pages.
3. Place tables and figures as soon as possible after they are referred to in the text.
4. Give each table and figure a complete title and/or self-descriptive caption.
5. Give each table and figure a complete title and/or self-descriptive caption.
6. Define all symbols used.
7. Number all equations. (Place numbers near right-hand margin.) Each equation should be on a separate line. Use complete sentences and fit all equations into the sentences that introduce them.
8. Avoid imprecise, vague, or unclear language. Carefully define your terms and use them consistently. Avoid jargon and excessive abbreviations.
9. Tell a story. Organize your information so that the narrative proceeds smoothly and logically.
10. Use SI units unless there is a compelling reason not to. That is, use μm or nm, but not Å.

Don’t’s

1. Do not repeat every sordid detail from a lab diary; report the logically crucial ones.
2. Do not distort unpleasant realities; call it like it is. Don't attempt to cover up flaws in your data; do explain departures from theory when you can.
3. Do not scan someone else’s figure.

Technical Typography

1. Algebraic symbols (variables and constants) should be italicized. {$E = mc^{2} $}, not E = mc². In Microsoft Word, modify the fonts yourself or use the Equation Editor. In LaTeX type inline equations inside dollar signs: $E = mc^{2}$ .
2. Subscripts are italicized when they refer to symbols, but Roman when they are words

{$$ B_{\rm bar} = B_{x} \tan\phi $$} LaTeX: B_{\rm bar} = B_{x} \tan\phi

1. Vectors are written in boldface (usually not italicized), but their magnitude is set in italics. Functions such as sine are not italicized.

{$$ \boldsymbol{\tau} = \mathbf{M} \times \mathbf{B} \quad \text{or} \quad \vec{\boldsymbol{\tau}} = \vec{\mathbf{M}} \times \vec{\mathbf{B}} $$} LaTeX: \boldsymbol{\tau} = \mathbf{M} \times \mathbf{B}

1. Refer to the second figure as “Fig. 2''. Write out “Figure 2” if this starts the sentence.
2. Figures should have informative captions. Most people “read” a paper by looking at the title, abstract, and figures. By making the figures clear and the captions informative, you increase your chances of getting the reader to read the text.
3. Number pages.
4. Do not underline. Book titles should be italicized. Volume numbers should appear in bold. Example: D. Quayle, J. Irrepro. Res. 21 (1996) 1234. [Note that “1234” is the page number of the article.]
5. Get your symbols for units right: “Hz” not “hz”, “{$\Omega$}” not “Ohm”, “30°” not “30 degrees”. Note: units are not pluralized: don't use “secs”, “hrs”, etc. Never ever screw up the capitalization of SI prefixes: there’s a crucial difference between MHz and mHz.
6. Abbreviations (e.g., RLC, rms, etc.) must be defined when first used (except in a title, where they should usually be avoided).
7. A number and the unit that modifies it should be separated by a (nonbreaking) space (e.g., 50.1 Hz, not 50.1Hz). The space should be a hyphen when the number-unit phrase functions as an adjective before the verb (e.g., A 50-Hz signal was applied across points A and B). In Microsoft Word, head to the Insert | Symbol command and select the Special Characters tab to find how to insert a nonbreaking space. In LaTeX it is typed with a tilde ( ~ ).
8. To type a multiplication symbol in Microsoft Word, use the Insert | Symbol and select Symbol font to get the palette of mathematical symbols. Then select the multiplication sign and click Insert. In LaTeX use the \times command in math mode.
9. If you use superscripts as endnote markers, they should appear after the punctuation mark (e.g., “... is given by the Biot-Savart law.¹”) If you use numbers in brackets, they go before (“... is given by the Biot-Savart Law [1].”).
10. Do not start a sentence with a symbol.
11. Doan furget two speel cheque. An prufreed. Swapping papers with a friend for proofreading is often very helpful.