TechnicalWriting

Benjamin Bach edited this page Mar 11, 2018 · 11 revisions

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.

High-level tips

  • Start early. Writing is closely linked to thinking and if you cannot write about something, you haven't understood it. Hence, starting early (e.g. with an introduction) helps you clarifying many things.

  • Space = time = importance. Reading text takes time. The more space a text takes, the longer it is, and the longer it takes to read. When writing parts of your paper, think of the space you attribute to a text as proportional to its importance as it defines how long a reader will deal with this part. The most important implication of this is that you should detail the parts that talk about your work, while shrinking the parts that do not talk about your work. An exception is abstract and introduction. They are very important, but therefor they stand in the beginning. Still, keep them short and to the point as they are not contributing anything.

  • Iterate. Iteration will reflect the pace of the evolution of your thoughts and help evolving them in return. You will automatically improve with each step. And in case you are not improving, then you have a strong case that the previous version was perhaps better. You can reset or retry. Both will help you improving. Iteration is in particular important for the introduction. Even the very successful writers and researchers write several introductions. It's perhaps the hardest part of each paper.

  • Reference Figures. Though everyone likes figures and more so 'browsing just the figures', figures are not part of the text. They are figures while the text is a linear and logical unit. If you are including a figure, reference it and explain it. A figure is not there for illustration but to help you making the point for the reader; to help him understanding. Think of the moment in a presentation when you show a specific figure. Without referencing the figure, the reader will most likely not look at it and hence lose the message. More important, the text should be understandable almost without the figures.

  • Be explicit. Do not make the reader (reviewer) think. If you have to think a lot when reading someone's text, how likely are you to continue reading? Exactly. Thus, don't make your readers think. Be explicit, even if it takes space and better add one or two additional explanations or examples that help following your point. You can ask a colleague later if it's too lengthy and if you should remove parts. Removing is always easy and you will get a good feeling over time.

  • Inform. The objective of technical writing is not to entertain the reader, but to inform. Readers are not reading your work to bridge their time, but invest their time to read your work. Hence, be to the point and help them saving time. The less it takes them to understand your work, the longer their will read it (and cite!).

  • Detail your methodology. Your methodology is everything the reader has to assess your credibility. Without methodology, you might as well have made up all the results and created the pictures in photoshop. Where are your results and conclusions coming from? A strong methodology adds credibility to your results. Having asked 1,000,000 people about whom they will vote for gives a much stronger result than having asked 10; having asked people in different parts of the country will be stronger than having asked your best friendsl; having designed 5 prototypes implies you have learned more than having designed 1, etc. Thus, a good methodology explains the details (details are important and show that you have really done it and thought it through), highlights the strong points (how many participants, what background, etc..), and explains why each step was necessary (and not another one).

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

  • State the contribution.

Introduction

  • State your contribution
  • State type of contribution (survey, sudy..)
  • State methodology
  • State outcome and impact
  • Mention URL if available
  • Mention external collaborators is present
  • Why, What, How
  • Explain project names that might not be understandable
  • State the contribution.

Related Work

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 only of limited information. It means you have read all of them (never cite without reading the paper!), but you have not understand the larger picture. Start from the large picture and tell us what are the main trends/technologies/concepts are related to your work. Then, insert the references were they fit your story. If a reference doesn't fit, it probably isn't important. Or, you're missing a part of the story.

Discussions

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. What did you we (you) learn? What are the unsolved problems (technical, conceptual, global) and what are the things you can talk about with some more 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.

Resources

Clone this wiki locally
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.