IRF Uppsala

Space Plasma Physics
Publications
Cluster
...EFW
...Quicklook
...Operations
Rosetta
...LAP

## Student project reports

Anders Eriksson
Swedish Institute of Space Physics, Uppsala
, and
Department of Physics and Astronomy, Uppsala University

The written report is an important part of your project: no project is of any use if not well reported, and the written report is what will remain when your and your supervisor's memories have faded, which unfortunately is likely to be a much quicker process than you may think. In addition, the project report is the only part of your work which future employers will see, and possibly one of the things they will care most about when they consider hiring you, as the ability to communicate your results is fundamental to almost all technical and scientific work, in industry as well as in academia. Here are some things I have learnt from 15 years of student project supervision.

### Start writing immediately

The best way to make sure that your project will not finish on time is to plan like "first I will do the job, then I will write the report". Start writing your report on the day you start your project! In this way, it will also be much clearer what is important to do, as the logical structure of your work is seen most clearly in your report. And you keep focus on your report, which in most cases is the most important product of you project -- often the only product!

Who are you writing for? Not mainly for your supervisor! You will show your report to prospective employers not so much for showing what you have done, but primarily to show them that you can document and describe your work in an understandable and attractive way. The best audience to have in mind is probably your fellow students (some of which, in the current system at Uppsala University, actually may scrutinize your report): if they can understand what you write, you have found the right level.

### Write a story!

Be sure that you know why you write every section in your report, and to tell this to the readers. At the start of the report, give a clear outline of the logical structure of the report: "first we do this in Chapter 1, which leads to the investigation of that in Chapter 2", etc. At the start of each chapter and section, tell what you will do here, and how it fits into the general picture. In this way, the reader will always know why something is there -- and you have to clarify for yourself as well, which sometimes can be a great help.

### Use a balanced style of writing

This is admittedly one of the tougher points: you need to navigate between several possible style problems. Use as direct and uncomplicated prose as possible without losing precision or going into the realm of spoken rather than written language. Be clear and to the point. If you like, you may possibly add a few poetical decorations in some places, preferably in the introductory and concluding sections, but be sure that you do not spread flowers around the bulk of the text. Write in active tense, but mostly use "we" rather than "I", as "we" includes the reader while "I" excludes her/him. I find the active "we show" to usually be much better than "it is shown", which takes all the nerve out of the text -- I know you can find the opposite advice in some places, but highest authority is on my line: check out "Wheeler's rules of writing" summarizing John Archibald Wheeler's advice for how to write good physics. He knew!

### Cross-references

Have a lot of cross-references. This is easy in LaTeX (which you should use, see below), and is a great help for the reader. Instead of "as shown earlier" write "as we showed in equation (18) on page 9", which in LaTeX will look something like "as we showed in equation~(\ref{eq:ohm}) on page~\pageref{eq:ohm}". It's easy, and great for the reader!

### Graphics

A lot of graphics is usually nice. However, all figures should be commented on in the text and have a role in your story. No free-floating figures unrelated to the text! And be sure to explain the diagrams in detail, in the text and in the caption. Reports usually include all the relvant figures presenting the data, but often lacks sketches and cartoons illustrating the ideas. When you describe principles and concepts, perhaps you can draw a figure illustrating them? Good graphics helps understanding immensely -- or why do you think the newspapers are keen on news graphics illustrating major news events?

### Lists and tables

Look for possibilities to use lists and tables: think "can what I just am writing be itemized or put in a table?" all the time. Whenever there is some kind of description of steps or events where each step is too short to merit an own subsection, a bulleted or numbered list, or sometimes even a table, is likely to be better than running text. Lists have the obvious graphical advantage of telling the reader that here there is a series of steps, and to show how many there are, thus bringing greater clarity to your text. And it helps you avoid list-like writing -- quite possibly the most boring kind of prose to be found -- in the flow of your main text. But use your judgement: just a collection of lists will not do either. I might have used a list for the three logical items "clear and to the point", "poetical decorations" and "active tense" in the section on balanced style above, but I thought the pace here was sufficiently high and the items less distinct that youre reading would in this case benefit more from a direct narrative. Perhaps you do not agree?

### Math is prose

Math is like ordinary writing: you can read it out loud, forming complete sentences. Hence, if an equation is last in a sentence, you should end it with a period, and use commas and colons and whatever as in any text. This is obvious in ordinary inline writing (like "Ohm's law is U = R I."), but should be used also when equations are on display as separate objects:

"Ohm's law is

U = R I,

but we here use it on the form

I = U/R."

This can become somewhat ugly when your sentence leads up to a large system of equations, with several alternatives and the last line ending with "q = R g y,   y > 0" or something like that. Try avoiding this by rewriting your text, and use your own judgement. No rule can ever cover all situations.

### Use LaTeX

OK, it is possible to write reports in e.g. MS Word or OpenOffice, but I would not recommend you to do so. For small documents, such software is all right, but when your report grows, LaTeX will become more and more efficient. In addition, the math handling is superior in LaTeX: it looks nicer, and is more convenient to work with than tools like EquationEditor (you may not think so when first starting with LaTeX, but break-even will come very soon, after 15 equations or so). There are several editors tailored for LaTeX, including kite for linux/unix, TeXshop for MacOSX, and LEd and WinEdt for MS Windows, but any text editor will do: I mostly use plain vi.

### Typography rules in LaTeX

One can argue infinitely about notational and typographical issues. Here are my choices, most of which are in fair harmony with common usage in the physics community. Most is about math, but the first is a general one often missed by beginners.

#### Periods and dots

There is a world of difference between the period dot ending a sentence and the dot ending an abbreviation. LaTeX believes all dots are periods unless you tell it otherwise, and will put a larger spacing after the period than between other words. Thus you must write "e.g.\ bicycles", not "e.g. bicycles" in LaTeX, to be sure not to get a strangely large gap between "e.g." and "bicycles".

#### Variables in italics

This means that Ohm's law looks like U = R I, not U = R I. When you write it in LaTeX, you thus write $U = R I$ or, if it is a spearate equation on a line of its own, $$U = R I$$. So far so good, but now comes the parts where you need start thinking:
##### Index subscripts in italics
If you have a set of N resistors (N is a variable and hence in italics!), their resistances should be numbered as i = 1, 2, 3, ..., N, with individual currents and voltages. Here i is a variable and hence in italics, so we write Ui = Ri Ii, which in your LaTeX code looks like $U_i = R_i I_i$.
##### Label subscripts not italicized
If you have two resistors, labelled "in" and "out" for example, then "in" and "out" are not variables but labels, and should not be in italics: Uin = Rin I, which in LaTeX becomes $U_{\rm in} = R_{\rm in}$. The proton mass is mp ($m_{\rm p}$), not mp, because p here is a label for the proton, not a variable that can take any value. And if you need to keep track of the velocity vector of the protons in your i:th simulation, that should be denoted vpi with only one of the subscripts in italics, i.e. ${\bf v}_{{\rm p}i$ or $\vec{v}_{{\rm p}i$.
##### Operators not italicized
Operators are not variables, and are usually not in italics. We thus write dy/dx, not dy/dx: in LaTeX, ${\rm d}y/{\rm dx}$. LaTeX is prepared for much of this: hence, to get cos x instead of the ugly cosx, we just write $\cos x$.
##### Units not italicized
Units are never in italics. Hence, just write "the voltage is 30 V" in LaTeX as "the voltage is 30~V", without any dollar signs anywhere (but with a ~ to make sure that there is no line break between value and unit). Also note that the full name of units should not have capitals and that their spelling may differ from the names of the people they honour: thus, write "1 A" or "1 ampere", not "1 Ampère" (which presumably would mean a lady or gentleman of the honourable Ampère family rather than the strength of a current, though I admit that mixing them up is rather unlikely).