Advice on writing UG4 and MSc project reports

Goals of this page

This page contains advice that I find myself giving repeatedly to students writing honours and MSc project reports. Reading it should help you with the content and organization of your report, especially the introduction.

In addition to reading this page, make sure you know the assessment criteria! As you are writing and editing your report, ask yourself: have I addressed these criteria?

Who are you writing for?

The short answer is: write for your intended audience. Say only what needs to be said to convince them your goals are important, you took the right approach, and your conclusions are well-justified.

But, what does that mean? One of the hardest things to get right for beginning writers is having a good model of the "intended audience".

Your "intended audience" is not always the same as your actual audience. For a UG4 or MSc report, your actual audience is me (your supervisor, i.e., the first marker) and some other staff member (the second marker). But it is more reasonable to think of your intended audience as someone who could be either a member of staff in a related area (say, NLP or machine learning) or some other student who has perhaps taken similar classes to you, but does not know anything about the specific topic or goals of your project.

Keep this in mind when planning your introduction and background sections using the tips below.

The introduction

This is often the section that students have the most trouble getting right, perhaps because they are not sure (or are misguided) about what should be in it.

Your introduction needs to answer the following questions (not necessarily in this order):

  1. What is/are the goal(s) of your project?
  2. Why are these important? (Motivation for the project)
  3. How did you go about tackling the goal(s)?
  4. What did you actually achieve/what are your results?

You should also be clear about whether others have attempted something similar, and if so, how your approach/solution differs from theirs.

Of course, you may also need to include a few other things like explaining some terminology or a small amount of high-level background information so that you can answer the above questions without losing the reader, but answering the questions should be the main point. I'd expect it might take 2-4 pages to properly address these questions.

The introduction should only spend time defining terms and discussing related work just enough to be able to answer the above questions. Any additional background information should go in the following Background chapter.

If you're writing a UG4 report, please also note the official UG4 report guidance:

"This chapter [introduction] should include a clear and concise summary of your contributions (examples: adapting a suite of existing code; interpreting a theoretical algorithm; coding; testing; conducting an experiment) preferably as a bulleted list".

These may be a combination of points from questions 3 and 4 above which you can summarize as the bulleted list.

Background section

Your background section/chapter typically serves two purposes, which I'll discuss in turn:
  1. To provide further details of the context and motivation for your work, building on what you said in the introduction. This part is often achieved by a review of literature.
  2. To provide some of the technical background that may be necessary to understand the methods you are using (especially if you are building on existing methods).

Reviewing the literature

The aim of a literature review preceding novel work (whether in a proposal, research paper, or thesis) is not to describe in detail every paper you've read that is related to the topic of your work.

Rather, the aim is to support the argument(s) you are trying to make: that there is a question or problem to address and that your chosen method is well-justified as a way to address it.

Too often, students review the literature by writing a sequence of paragraphs, each one describing a different paper. For example:

One approach to this problem was made by Smith and Li (2007). They did X (providing several sentences of description) and found Y (several more sentences). Their approach had the advantage of A but did not solve B.

Gupta and Milch (2009) presented a different method, based on Z. In their work, they did Q and P. They showed that including bag of words features improved the results, which is why I plan to do so here.

[...more paragraphs, more papers...]

The second paragraph above does begin to justify a particular approach (and the first paragraph might also, if that approach is intended to solve B). But in general, a much better way to organize your literature review is by first identifying the argument(s) you want to make, and then organizing your review around the argument(s).

This approach typically leads to a different style of paragraph. Instead of each paragraph describing a single paper, each paragraph will contain a single controlling idea or claim. Typically (but not necessarily) that claim will be stated in the first sentence. The remainder of the paragraph will provide evidence for that claim. In many cases that evidence may come from more than one paper, but it's often unnecessary to provide much detail about each of those papers in order to support the claim. For example:

Over the years, there have been two main approaches to this problem: X (cite1, cite2, cite3) and Y (cite4, cite5). Here, we follow approach Y because it has property Q (cite4), which is more suited to our setting.

The results of cite4 and cite5 also provide some preliminary evidence that Z may be an important factor in the success of these models. In particular, cite4 showed A and cite5 showed B. However, their experiments are not entirely convincing because P. Therefore, we plan to experiment with both Z and ~Z and directly compare results.

There are some situations in which it is appropriate or even necessary to describe the details of previous work, simply as a description. The most common case is when your own work follows the previous method very closely, in which case the reader needs to understand the details of that previous work in order to understand what you have done. It may also be appropriate to describe details of methods you are comparing directly against. Other than that, be wary of "description" paragraphs in literature reviews.

If after reading this you are still confused about the difference between a "description" paragraph and a "claim-evidence" paragraph, you may also want to read UNC's guide to paragraph development. (What I call "claim-evidence" is their "illustration" paragraph type.)

Technical background

Again, the goal here is not simply to show your marker that you can repeat lots of information about neural networks, HMMs, the history of speech recognition systems, or whatever. Your goal is to target your intended audience and provide information at the level of detail that is needed for them to understand what you did and why.

For example, do you need to include all of the equations describing the architecture or normalization of your neural net? If you are using standard methods in standard ways, then probably not. But you probably do need to say why you chose those methods (see Literature Review above), and you should include enough detail about how you put the pieces together so that your reader doesn't need to make guesses about that.

Of course, if your project revolves around making changes to detailed technical aspects of existing methods, then you probably do need to include a lot more detail here.

Sectioning, transitions, and main points

Be wary of using very large numbers of very short sections, and/or using section headings as a crutch to indicate the structure of the document. The section headings may make sense to you, but by themselves they are often insufficient to make the document structure clear to the reader; instead you should make sure the text itself includes transitions, introductions, and/or conclusions that clarify its structure, giving the reader a sense of direction. Consider what would happen if you removed the section headings. Would the document make any sense? A clearly structured document ought to. Crucially, you need to make sure that the main point of each section is clearly stated (i.e., why have you included that section in the document? What is it supposed to tell us?), and that this point is clearly related to what came before (and often, what will follow).

Normally, the main point of each section and the transitioning/context information should come as an introduction to the section, which could be just a sentence or two for short (sub)sections or could be much longer. Introductions may or may not have explicit section headings--usually you would only put a section/chapter heading on an introduction at the beginning of a full paper, or (for a multi-chapter document) at the beginning of the whole document and each chapter. Otherwise it should be:

text introducing main point and how the subsections relate to this point
stuff 1
(relationship of C to B and/or to the main point of A)
stuff 2

In addition, for any medium or large section of a long document (including sections shorter than a full chapter), consider: would it help the reader to include a conclusion that reminds them what the main point of the section was and again fits things into the context of the larger chapter/document (often including what are the missing pieces that the following sections will fill in?). The conclusion doesn't have to be a separate section, it could just be a couple of sentences at the end.


Use judgement about what to include

Don't try to impress your reader by just including lots of results. You should spend time looking at all your numbers, thinking about them carefully, and deciding what the main points are, precisely so that your reader doesn't have to. Once you have decided the main points you want to make (these should be guided by your main questions/hypotheses), figure out the best way to present the results so that these points come through clearly. Very often that means NOT presenting all the results you got, and very often a well-designed figure (or several) will make the point much more clearly at a glance than a table with many numbers.

If you did some preliminary experiments that were needed (say, to find reasonable hyperparameters) but are not that relevant to the main thrust of your report, just mention briefly what you did in those preliminary experiments and why, and (if you want) put the detailed results in an appendix. Save the main report for the interesting results.

Get the basics right

Make it easy to do again

If you haven't already, write scripts to do things like collating your results into consistent formats (e.g., .csv) and/or converting these into LaTeX tables that you can paste directly into your thesis, or automatically generated figures. You may think you will only need to copy results or generate a figure once, but you'll almost certainly need to do it again after you discover a bug or re-run an experiment. Scripts will save you time and mistakes in the long run.

Last modified: Mon, Jul 22, 2019 3:53:24 PM