Logo: VisHub University of Edinburgh, Visual+Interactive Data


Interdisciplinary research lab in data visualization and HCI at the University of Edinburgh.

Home - Publications - Research
People - Jobs+PhD Projects
Equipment (kit) - Resources
Teaching - Outreach
Projects/Tools - Student Projects

https://vishub.net



Logo of Design Informatics at the University of Edinburgh Logo of the School of Informatics at the University of Edinburgh Logo of the University of Edinburgh

Technical Writing

The below is a rather loose list of thoughts stemming from my own experience as technical writer, reviewing tons of academic papers, and student dissertations.

General Guidelines

Two Phases of Writing

Phase 1: Understanding. This is the phase where you understand your own work and flesh out what you are really doing. I.e. what is your problem, what are you focusing on, why are you chosing the methods you chose, what is your contribution. This phases is extemely important and can take a long time. Use the writing to understand your research. At the end of day you and everyone very famililar with your work will agree on what they do and will have a language to discuss their work.

Phase 2: Communicating. This is the phase where you communicate your work to others. You need to take your wrtiting and optimize for communication to everyone not involved in your work;

Random Notes

The below advice is collected from many recurring errors in students’ writings.

Possible Outline and Section Content

The below structure follows the standard in technical writing. You can use it as a check list when preparing your submission. However, there are many cases you may want to adapt the structure. If you are in doubt, the best is to stick to this structure. It mostly works. (Duplications in the below list are on purpose -> space=time=importance).

Abstract

The abstract is the first (and often only) piece of your paper that anyone will see after the title. The abstract will decide if someone deems your paper

Hence, it’s important your abstract is like an exciting teaser. However, other than a movie teaser, your abstract should clearly reveal the contribution (ending!). Make it easy for people to understandng and appreciate your contribution and learn from your work.

A good abstract contains (and probably in this order of priority):

In most cases, you have only 1-2 sentences for each information. So, be very specific and explicit.

When I write abstracts, I try to take the role of a third person not involved in this paper, e.g., someone from my targeted audience, ideally a reviewer writing a short summary of the paper they just reviewed. That helps me focus on the ‘so what’ and the importance of the paper. Ideally, circulate your abstract to peers. It’s extremely useful since everyone loses context over their very detailed work. It can take weeks to write a good abstract.

A possible structure for an abstract could be:

Example:

We report on a controlled user study comparing three visualization environments for common 3D exploration. Our environments differ in how they exploit natural human perception and interaction capabilities. We compare an augmented-reality head-mounted display (Microsoft HoloLens), a handheld tablet, and a desktop setup. The novel head-mounted HoloLens display projects stereoscopic images of virtual content into a user’s real world and allows for interaction in-situ at the spatial position of the 3D hologram. The tablet is able to interact with 3D content through touch, spatial positioning, and tangible markers, however, 3D content is still presented on a 2D surface. Our hypothesis is that visualization environments that match human perceptual and interaction capabilities better to the task at hand improve understanding of 3D visualizations. To better understand the space of display and interaction modalities in visualization environments, we first propose a classification based on three dimensions: perception, interaction, and the spatial and cognitive proximity of the two. Each technique in our study is located at a different position along these three dimensions. We asked 15 participants to perform four tasks, each task having different levels of difficulty for both spatial perception and degrees of freedom for interaction. Our results show that each of the tested environments is more effective for certain tasks, but that generally the desktop environment is still fastest and most precise in almost all cases.

Introduction

The introduction is perhaps the most important part of your paper. Take specific care of it. Most people won’t necessary read beyond the introduction and based on abstract and/or intro will judge whether to cite or in the worse case reject your paper. The introduction sets the tone. If you do a good job in detailing your motivation, method, and contribution, your work gains credibility. Different from the abstract, the introduction usually follows the slightly adapted structure:

Within this structure, cover the following:

This section, usually following the introduction provides the knowledge the reader needs to know to understand your contribution. A good background section can support your motivation of why this research is necessary as well as support your contribution to the state-of-the-art. Write the related work with these objectives in mind.

Calling this section ‘Background’ or ‘Related Work’ depends a little. There are no real rules when to use which term. I would use background if I have to talk about general knowledge such as the description of a domain my work is situated in (e.g. protein interaction, peace agreements, Islamic History, etc..). Here you want to talk about specific terminology, previous work, and current challenges. In a related work section, your focus is on related research addresses a similar goal or question than you.

If it is not clear from your intro which areas you are covering in your thesis, start your related work with a brief overview which areas you are talking about and why.

Your related work should tell a story. Don’t start with the references and write a ‘laundary-list’ of the form ‘X did blah‘. This is of very limited information. It means you have read all of them (never cite without reading the paper), but you have not understood the larger picture. Start from the larger picture and tell us what are the main trends/technologies/concepts are related to your work. Then, insert the references were you need them. If a reference doesn’t fit, it probably isn’t important. Or, you’re missing a part of the story.

Also, balance detail and brevity. Some references are more important than others. Talk about the more important in more detail, while keep the less important to the minimum. It’s ok to reference 2 or even 3 sources in one sentence, e.g., “other approaches had yielded similar results [1,2,3]”.

Relate your work on the related work (hence the name). Make this relation explicit and don’t let the reader think (G5). If you can’t tell what’s the difference, search for arguments and make it clear. It shows how your work advanced and complements existing work. It also shows that you know why you are doing something specific and that have the knowledge of the literature to judge your contribution.

Discussion Section (‘Discussion’)

Discussions have two purposes: reflection and outlook. Reflections critically discuss your own work, its achievement, and limitations. Research is flux and each work (should) bring some certainty and some more knowledge about the uncertainty we’re facing with this certainty.

During writing, it helps listing candidates for a discussion. When you finally write that section, you will know better what you can keep and what to drop. You do not have to discuss everything.

Conclusion/Summary

This can be short, summarizing your achievement and tell what others can do with your great work. What is your high-level take home message?