Tips on technical writing.

I have started writing a series of blogs on the topic of technical writing. There are many good books out there that you can explore (I will make a list of these book some day when I have time) but I have rarely seen any student reading anyone of them. These blogs are intended to be short and topic-based, and are based on my own experience when supervising or grading student projects. My goal is to write down my observations and my proposals for improvements in a simple way so that these tips can be of practical value to my students. Please comment and ask questions if you need!

Current posts on the topic of technical writing:

• Clearly defining and justify your research problem.
• Reveal your secrets as early and as often as possible.
• The importance of terminology in technical writing.
• Writing the abstract.
• Why and how to write the state-of-the-art.
• How to submit interim versions of your thesis for review by your supervisor.

Clearly defining and justifying your research problem.

Defining your research problem is the single most important, and at the same time the hardest part of your research. It is my experience that most students (and their supervisors) spend too little time on defining what they really want to do and why. This results not only in unmotivated students and supervisors, but also in highly unfocused reports where there is little relation between the different chapters. And even worth, you might end up spending half a year or a year of your life doing research that no one really cares about!

I have no clearcut advise on this topic. Defining a research problem is a dialog and needs to be done continuously in the course of your research (but justification should preferably be there from the beginning!). Some guidelines that I find useful for myself:

1. Be as critical as you can be! Always ask the question: What would happen to the world if I stopped doing this research right now? If no-one would care, then you should stop your research. But normally there is someone who cares, e.g. your supervisor. If it is only your supervisor who cares, then go ahead and challenge your supervisor (ask him/her why only he/she cares and no one else).
2. Find and know your beneficiaries! Often it is not true that no one cares about your research (thanks God). No matter how obscure your invention is, someone could think of paying for it. Know who that someone is even if your research is not obscure.
3. Have a serious talk with your beneficiaries! Imaging you were a door seller, trying to sell the end product of your own research to your beneficiaries by knocking on their door at dinner time. How would the conversation between you and this hungry, disturbed, annoyed beneficiary be? While the only thing he/she is thinking about is to go back to his dinner? Remember that there is a big difference between you and a real door seller: you are not approaching an arbitrary person, you are approaching your beneficiary! So don’t be shy!
4. Look into research done by other researchers (ask your supervisor!). Often you are not the only one who wants to solve exactly this problem. The world is full of researchers. If no one has looked into the same or similar problems as you want to look into, then you should ask yourself why. And why you are waiting for an answer, take another look into this site.

Reveal your secrets as early and as often as possible.

Remember, you are not writing a crime fiction! This is a very common mistake in technical writing, and is a very annoying one as well, especially for the reader! It is common practice in literary genres such as crime fiction that the writer follows a very secrete plot when telling the story. The writer does not want to reveal any secrets that will spoil the plot. This approach should be strongly avoided in technical writing! You must reveal all your secrets as soon as possible! There are many ways of doing this in a report:

1. Get institutionalized! Make it a habit to sum up whatever you are trying to say in 1-2 sentences in the beginning of your block of text and 1-2 sentences in the end of your block of text. E.g.:
2. The abstract and the conclusions: The first and the best place to reveal your secrets is in the abstract of your report/paper. The abstract should tell in short what problem you addressed, what method you used, and what results you achieved. So no secrets left! Also a good idea to summarize your revealed secrets in your conclusions so you are sure you don’t leave anything to guess work and fantasy.
3. The chapters: Introduction to each chapter should state shortly what secrets you intend to say in that chapter, and the summary should summarize the revealed secrets.
4. Sections and paragraphs: Each section and even each paragraph should have a short sentence in the beginning to give a hint of what you intend to say in it.
5. Don’t hide! Never hide!

I am not sure what the reason for this annoyance is, i.e. why readers get annoyed when technical writings are mysterious. Maybe the reason is that the reader of a technical report/paper is not expecting to be confronted with a crime fiction, and they feel cheated. Another reason in my view is due to the complexity of technical text; if the user does not have a clue of the goal of the text, it is difficult to follow the text and use the sentences to build a mental model of what the writer wants to say.

I also strongly believe the reason for writing mysteriously is that the writer does not have a clue of what he/she is writing about!

The importance of terminology in technical writing.

One of the main problems reading an immature technical text is that it does not make consistent use of a clear terminology. A clear terminology emerges as you do your research, and you need to be in control of it. Even the simplest and most obvious concepts need to be referred to in a consistent way (e.g. “user” or “end user” or “customer”, which one to use?). Here are some suggestions:

1. Explicitly define and continuously refine your terminology: Work continuously with your terminology and give meaningful names to things you define. If you see yourself repeating the same sentence many times in your text, this sentence might be a candidate for being replaced with a term/name. Do your terminology work systematically. Use a table or, even better, UML class notation to be as formal as you can. Being formal in technical writing is not a bad thing!
2. Get to know the jargon of your field: Once you have defined your research topic, try consciously to learn and use the jargon commonly used your field. Don’t forget to include the jargon in your terminology table!
3. Define your terms the first time you use them: In your report/paper don’t forget to provide a short definition of your terms the first time you use them. Don’t use a term without also showing what you mean by that term. Preferably index your first definition of a term in your index chapter at the end of the document so it is easy to look up definitions (or have all your definitions in a table).
4. Use your terminology! Don’t just define the terms, use them consistently in your report. Using the defined terms consistently not only allows the reader to quickly become familiar with them, but it also makes your text more consistent and more compact.
5. Don’t overdo! The only terms that need to be defined by you are the ones directly related to your problem domain. This is tricky as it takes time to develop your understanding of your problem domain, and to focus your writing. There exist accepted definitions of many terms out there (e.g. in wikipedia). Use these definitions as much as possible for terms that are not central for your problem area.

Writing the abstract.

The abstract is an important part of your report and will in most cases be the sole determinant of the impact of the research you did. So it is better you spend some time writing a good abstract. The abstract is normally written as a stand-alone text (ranging from a paragraph to a whole page or more) that summarizes your article/report. In 99% of cases it is the abstract that will determine whether someone will read your report or not.

In today’s world there is so much information around that your article/report will be very hard to spot. Any researcher in search of literature will rely solely on the abstract of an article/report before deciding whether that article is of any interest. If the abstract does not in a clear and concise manner say what you did, your larger article/report text will not be attractive to anyone because they will not know what is in it (because they don’t have time and do not see why they should read your article/report).

In order to know what should be in an abstract consider what the abstract will be used for:

1. Knowing your research problem: Maybe the single most important reason a researcher will read your article/report is because you are trying to solve the same research problem as he/she is. It is important that your abstract includes a short and concise description of your research problem, preferably stated using the terms and jargon of the research field.
2. Your research method: The same problem can be addressed in radically different ways. E.g. the problem of aging in place can be addressed architecturally, medically, socially/politically, technologically etc. If your research is related to e.g. solving the problem of aging in place, and you constructed and tested a piece of technology to this end, you should emphasize this in you abstract by saying that your approach/method was that of developing and testing technology (and not, say, changing public opinion about aging in place).
3. Your results: In order to allow others evaluate whether your research is important or not, you should summarize your most important results and findings in your abstract. There is no meaning in hiding your results, and the abstract is the best place to expose these!
4. Archiving and search: Abstracts are archived in databases and are in many cases the only part of your text that will be searched. Although most search engines search also inside an article/text, searching abstract is of more value if the most important terms and keywords are present in it.

So, go ahead and write your abstract now!

Web resources:

• Example abstract: One of the better abstracts I have seen lately. It is from the paper titled “A Developers Bill of Rights: What Open Source Developers Want in a Software License” by Alan MacCormack. The abstracts is so well-written that it gives a complete overview of what MacCormack’s paper is all about. The abstract starts with a problem definition, gives a short motivation for the problem, tells how he addressed the problem, i.e. methodology, and what the results were. The abstract concludes with an optional part on the usefulness of the paper in general.
• How to get your abstract rejected. By Mary-Claire van Leunen and Richard Lipton. Give some advise specific to ACM SigSoft conferences, but still a good read.
• Advise to authors of extended abstracts. By William Pugh. Some conferences require what is called an extended abstract for their first round of submission. An abstract for a thesis does not need to be 2-3 pages (as an extended abstract will be). However, there are some very useful hints in this page.

Why and how to write the state-of-the-art.

State-of-the-art (SoTA) is a step to demonstrate the novelty of your research results. The importance of being the first to demonstrate research results is a cornerstone of research business. You cannot get a Nobel prize (anymore) by learning Einstein’s law of photoelectric effect by heart and presenting it as your own. Einstein did it before you, and everyone knows it. When Einstein presented his theory the theory had novelty. Einstein could demonstrate his theory’s novelty by presenting a SoTA and showing that no other researcher had ever presented such results. That’s why he got a Nobel prize and you will not.

Besides demonstrating the novelty of your research results, a SoTA has other important properties:

• It teaches you a lot about your research problem. By reading literature related to your research problem you will learn from other researchers and it will be easier for you to understand and analyze your problem.
• It proves that your research problem has relevance. If many people are trying to solve the same research problem as you, and if you can demonstrate this in your SoTA, then no one can tell you the problem you are trying to solve is not important.
• It shows approaches to a solution. By seeing many different approaches taken by other researchers, you can evaluate your own approach and realize its novelty (or lack of it) easily. You can also see which approaches are the most popular and which are dead ends.
• It shows what you can reuse from what others have done. Especially when doing research on new software, it is amazing how many people have made the exact software you are planning to make. Just take a look at sourceforge.

So how to write a good SoTA? Writing a good SoTA is 110% dependent on having a clear problem definition. If you have failed in defining your problem clearly, you will fail in writing a good SoTA. The reason is that you will not know what related research you should investigate. So if you have problems with your SoTA, please go back and work on your problem definition! Here are some steps/hints on starting to write:

1. SoTA is not a one-way road. You will not sit down one evening and write your SoTA. You will do it all the time while writing your paper/report. Knowing what other researchers are doing should be a part of your life for all the duration of your research. So an important step is to create a system of registering and summarizing what you read. Use some bibliography software such as BibTeX or EndNode, register everything you read, and register your understanding of what you read, in your own words.
2. Be critical when choosing your literature. Don’t read everything. There is a LOT of garbage out there on the web, and you don’t want to waste your time. One important criteria for choosing your literature is to make sure that it is peer-reviewed and is already presented/published in well-known conferences/journals. In case of technical IT-related stuff, ACM and IEEE are good places to start. It is also a good idea to set up an initial SoTA literature list together with your supervisor.
3. Stop reading! Make an initial selection of literature (10-20 papers, depending on research problem) and stick to these for a while. Don’t go on finding new papers all the time, or you will never finish your thesis!
4. Spend time on analysis and not on making summaries! A mere summary of 10-20 papers is not a SoTA. There is software out there that can summarize any paper for you, automatically and much faster than you ever will be able to. Your summaries become a SoTA only when you relate the papers to your problem analysis.
5. Always give credit! Not giving credit for others’ research is also called plagiarism.

How to submit interim versions of your thesis for review by your supervisor.

This topic is for you and your supervisor! It discusses a problem for your supervisor to allocate enough quality time to give you constructive feedback while you are writing your thesis. Most master theses become quickly 100+ pages. It takes a loooong time to read through them, and this might result in not only long evenings for your supervisor, but also inferior feedback to you from your supervisor (because he/she might fall asleep while reading your interim versions over and over again). The bottom line is that if you want good feedback from your supervisor you have to help him/her provide you with quality review time! Some tips on how you can structure your interim deliveries:

• Use change tracking! All word processors have a feature called change tracking that will allow you to mark lately edited text. This makes it easy for a reader to see what text was changed since last time he/she read the document. In MS Word you simply press Ctrl+Shift+E to activate/deactivate change tracking. See also this page. LaTeX uses a number of different methods, the one called changebar is a good one. Alternatively if change tracking becomes tedious you can mark the change/added text using colors.
• Use versions and a change log. Add a table to the beginning of your document, where you insert one row for each version of your document together with a version number, date, and main changes you have done to different chapters/sections.
• Keep track of the feedback you get. In many cases important feedback from your supervisor gets ignored (which makes your supervisor furious). Even if you don’t understand the feedback or you don’t think you should take any actions, keep the comments in your document. In MS Word you can add comments to different parts of your text. In LaTeX I don’t know how you can do this (maybe use footnotes).
• Keep track of older versions. Sometimes you might delete or edit text that you end up regretting. Use version control packages such as TortoiseSVN for not only backing up your documents but also keeping track of different versions of your documents. Remember to submit detailed change logs when you add new versions to your version control database!
• Be targeted when asking for feedback. Ask your supervisor which chapters/parts of your report need feedback every time you submit an interim version. This will help your supervisor to prioritize his/her reading.
• Don’t expect your supervisor to write your thesis! Respect the fact that your supervisor most probably has a lot of other things to do. He/she has not the luxury of focusing all his/her time on a thesis or a paper. Don’t expect many reads. Don’t send documents on Friday evenings, expecting feedback on Monday morning. Rely on your own judgment (remember you are the researcher!) and use these blogs. If you think new blogs should be added or existing ones should be improved, contact Babak. To see how your research will be judged I recommend you to read this article.