Technical Writing Tips
by Johannes Kinder
On this page I have collected some advice I commonly give to students on how to get started on their theses or reports; this page has grown and evolved over time, and in all likelihood will continue to do so. I wrote the original set of notes for final year project reports at RHUL, but the advice is generic and applies to any form of in-depth technical writing.
Structure
A report will typically follow a structure like the one shown below. Longer reports like BSc/MSc theses have chapters, shorter reports like seminar reports or papers only sections Chapter/section titles can vary depending on the nature of your project, but there will always be an Abstract, an Introduction, a Conclusion, and a Bibliography. All chapters/sections (and subsections) are numbered apart from Abstract and Bibliography. Appendices are numbered from A-Z.
A section should have either zero or at least two subsections, but never just one. If it has subsections, it is customary to start the section with a very brief (three lines) outline, like this: "We will now present an overview of our FOO algorithm (§3.1), derive its complexity (§3.2), and finally discuss potential extensions (§3.3)." Don't do this too early in the writing process, since it will change frequently.
Abstract
A short summary of the introduction, main technical contributions, and results. Should allow the reader to quickly judge whether the report is interesting for them. As a rule of thumb, the abstract shouldn't be more than 250 words.
1 Introduction
Explains what the project is about and motivates it. This includes explaining the problem you are solving and briefly explaining why it hasn't been solved yet. Ideally, you can phrase the problem in the form of clear research questions. At the end of your introduction, you list your contributions or achievements. Aim for 2-4 contributions; each should be a clearly identifiable separate aspect of your work, a certain technique, an important result, or a distilled piece of knowledge that may be useful for future students or other researchers.
The contributions also provide structure for your report, and you will usually have one chapter (or section) per contribution. The last paragraph of your introduction lists the remaining chapters of the report and points out what readers will find in each.
The goal of the introduction ist that after reading, one should be convinced that this is an interesting project and that it is worth reading on.
2 Background / Literature Review
Reviews basic background material, relevant academic or technical literature, e.g., important books or conference articles, manuals that are central to this work, etc. After reading this, someone with an average Computer Science background should be able to understand the following technical sections.
You can and should also cite relevant literature in any of the other main sections where appropriate. Citations in text are put at the end of a sentence (but before any punctuation marks) or part of a sentence in square brackets (see bibliography below). Using LaTeX makes this a lot easier.
Note that for seminar reports, BSc and MSc theses, this section covers the related work. In conference and journal papers, the related work tends to come immediately before the conclusion, with only the very most important related work being covered in the introduction already when introducing the problem.
3-5 Technical Chapters
Descriptions of various technical aspects of the project. What these look like depends very much on the kind of work you are describing. But taken together, these chapters will prove that your work was technically challenging and will explain any new concepts and techniques. All technical chapters need to be related to your project, and not purely generic background material (this would go into Section 2).
6 Results / Evaluation / Discussion
Present the outcome of what you did, any user feedback, performance evaluation, discuss limitations. The nature of the evaluation depends very much on the project, but the point is to convince the reader that the project was successful. If your introduction claims that you answer certain research questions, then the evaluation should provide experimental evidence for each of them.
For experimental work, this is typically where you validate your contributions, i.e., you show that your new technique is effective for a certain problem, sets a new state of the art, etc. The evaluation commonly answers questions such as: "Is the approach effective?" "Is the approach correct?" "Is the approach feasible in practice?". Each of these would go in a separate subsection.
7 Conclusion
Draw some conclusions from your work: what did you learn? Where is the project now? How could it be continued? What would you have done differently if you were to do it again? This is where you can reflect on how your project went overall, and where you can assess your own performance.
Bibliography
A numbered list of all academic / technical works you referenced in the literature review and throughout your report. Should follow standard IEEE citation style. Bibtex (or Biblatex) will do this for you. Just make sure you obtain the bibtex entries from DBLP.
Appendix A-Z
Anything that doesn’t fit anything above but you feel absolutely needs to be included, e.g., feedback questionnaires, extra data, longer code snippets.
topWriting
The prospect of writing may seem daunting at first, but if you did something interesting in your project, you will get there easily.
Getting Started
Always start with a rough outline like the one above. Consider how the topics mentioned in the project specification will fit into this schema, and start adding section and subsection titles. Think how you can build a story arc from the introduction, which sets up the motivation and problem space, over the background to the technical "meat" of the paper into the evaluation and conclusion.
As you fill in section titles, start making notes on what you are planning to write where; simple bulleted lists are fine. Put some thought into this, it's one of the most important phases of writing. Once you are done, discuss the outline with your supervisor who may suggest some changes, which are still easy to do at this stage. The agreed outline then serves as your roadmap for writing: you start turning the bullet points into text.
A rule of thumb is to turn each bullet point into one paragraph. This also ensures that each paragraph addresses one topic only and stays on message. A good approach that often works is that of the *topic sentence*: start off each paragraph with a sentence that clearly makes a point. The remainder of the paragraph then further explains and substantiates this point. If you do this correctly, you can read just the first sentence of each paragraph and still roughly understand the paper.
Getting Things Done
Start as early as possible with the outline and start filling in the bullet points as you do your initial research for the project. Set yourself a goal of writing X pages per day or per week. Writing cannot be rushed, and if you run out of time, your report will be terrible.
It's only natural that sometimes the writing doesn't quite come together as you planned. Don't be afraid to later "refactor" your writing. You can always move things around and restructure; just make sure everything still flows.
Quality Control
Possibly the simplest way to improve your report is to use an automated spell checker. There is absolutely no excuse to having any mistakes in your report that would have been caught by one. Next on the list is proofreading. Before you send a draft to your supervisor, be sure to have proofread your entire writing. Otherwise, your supervisor will be distracted by the mundane mistakes in writing and waste time pointing them out instead of giving you more valuable feedback on the contents, structure, and flow of arguments.
Stylistic Notes
Stick to a technical writing style throughout. I.e., do not just write up a stream of consciousness, and do not ramble on about your process of discovery. Instead, start with the right answer, start with your actual design. If you do want to discuss this, the space for reflection about the process is in the conclusion, possibly in a discussion section.
Avoid the passive voice, it makes your writing very hard to follow. Use short sentences in the active voice. You can use "we" (the authors) or "we" (the author and the reader) in sentences. If you are the only authors, it is OK to use "I" or "we". You can also use other subjects for your sentences, e.g., "the algorithm", "the prototype", "the experiments", etc.
When refering to the work of others, do not use the citation itself a subject or object in the sentence, but just as an addition. Instead, use the author names. For example:
- Do not write: In our experiments, we evalute our approach on the dataset of [23].
- Do write: In our experiments, we evaluate our approach on the dataset by Smith et al. [23].
... on the dataset by~\citet{smith2019-someconf}."topTools
I strongly suggest you use LaTeX to write your report. It works better with large documents than word processors like Microsoft Word or LibreOffice Writer, it is easy to achieve consistent formatting, and it typesets a professionally looking bibliography for you. There's a bit of an initial learning phase, but you'll get the hang of it very quickly, and there is a lot of help available online. Use versional control for your writing, it helps avoid disaster. Overleaf is fine, but you will be dependent on an internet connection.
To draw diagrams, you can use a vector graphics program or a LaTeX package like TikZ, which takes a bit more time to get used to. Do not use bitmap graphics like JPG or PNG, since they will not print well; unless you have to include a photograph, in which case you should use a high resolution (at least 200 dpi). This also means you normally shouldn't include graphics you found on the web. If there's just no other way, you must properly acknowledge the source of the image in its caption.
For tables, use the LaTeX booktabs package and avoid excessive use of horizontal and vertical rules. Make sure all numbers are aligned on the decimal dot and use the same number of significant digits. This is easiest to achieve just using right-alignment. You get more powerful options using the siunitx package.
Be very careful with AI assistants: ChatGPT & co may seem impressive at first, but they have a tendency to produce longwinded, repetitive sentences, which is the opposite of what you should aim for. Still, they can be useful for helping with your grammar, for instance, if you are unsure about the finer points of the English language. AI assistants can be quite useful for generating LaTeX code, especially if you are only starting out and do not know which packages are available.
Length
At the Deparment of Informatics at LMU, the required length of several pieces of writing is defined in the Prüfungsordnung. Please consult with the current one for your specific degree, below is an unofficial excerpt that was current at the time of writing:
- Final report for a Bachelor seminar: 7,000 - 14,000 characters
- Bachelor thesis: 40,000 - 80,000 characters
- Final report for a Master seminar: 20,000 - 30,000 characters
- Master thesis: 50,000 - 100,000 characters
You can use texcount -char for counting characters in one or multiple LaTeX source files.