The aim of technical reports is to convey information, discuss a topic with scientific arguments, present facts, or propose a solution or design and usually they are directed to a relevant audience. What happens though when someone is trying to convey technical information in a “non-technical” way? For example, for my PhD I looked into, you know, how to clean water, remove stuff from it using this powder which looks like sand actually it’s sand. So, I made the powder as we do in the lab and then I used it to put some enzymes in, it’s like baking a raisin bun, very cool. And then I put it in coloured water and I saw it going, it was great! It does not sound very technical or professional. I do not sound like someone who knows what they are talking about. To be clear, I am not referring to science communication or outreach cases where we actually need to be non-technical. I am referring to those cases where the deliverable is a technical report.
Recently I got a contracted job on looking through submitted reports for a highly technical module of a postgraduate taught course in engineering, and suggest ways of improving the technical writing skills of the students. I know what you might think, if we are talking about a postgraduate course in engineering, participants should know how to write in a technical manner. Based on what I saw, allow me to disagree.
Writing a technical report has to be done in a professional way that gets the message across, it is clear, of a high writing standard, transparent with regards to sources of information or inspiration used, in a document that is easy to navigate and read. Following these guidelines, I structured this article (or guide if you prefer) in three main sections: common mistakes that prevent a report from being “technical”, why these mistakes are wrong, and how to correct or avoid them. Let’s dive in! Or, more technically correct, in the next few paragraphs we will identify and talk about these mistakes.
Common mistakes identified in many reports
From what I saw in the reports I reviewed, and from my general experience in writing and editing technical documents, majority of the spotted mistakes and areas for improvement were either with regards to context, or format of presented information. Below is a list of the most common mistakes when it comes to context.
- Issues with in-text citation and referencing (format of it, position, or absence thereof)
- Issues with use of acronyms and abbreviations
- Very long sentences
- Use of indirect references/indications, to articles mentioned a few lines above (e.g. “this shows”, “they found”)
- Use of informal, very casual wording, and/or “oral speech” expressions
- Spelling mistakes of important terms/names
- Unfinished sentences, half sentences, sentences without structure, sentences translated from other languages
- Use of figures, tables, schemes that are not discussed anywhere in the main body
Before discussing why these mistakes are wrong, I thought it was appropriate to show the most commonly identified mistakes when it comes to formatting and discuss both together. Below is a list of the most common mistakes when it comes to context.
- Absence of table of contents
- Use of large amounts of text without breaking it up or using spaces appropriately
- Presentation of lists in plain text formatting rather than bullet/numeric points
- Absence of figure/table captions, legends, or references
- Absence of correct punctuation
- Showing a figure/table at the beginning of an answer or section, prior to any explanation
- Use of different fonts with no apparent reason (e.g. leftover from copy-paste activities)
- Use of illegible figures (usually copied-pasted from sources)
- Leaving headings “orphaned” at the end of the page, with the corresponding text starting at the next page
- Use of many different styles for the same purpose (e.g. showing 3-4 different referencing styles in the report or have different caption formats across figures)
Why these mistakes should be avoided in technical writing
As it was pointed out before, the point of a technical report is to convey information in a concise and easy way. The point is to focus on the technical aspects/information/data shown rather than admire the manipulation of the language of the author and award them a Pulitzer Prize or provoke feelings of “grabbing a beer” with the author. This means that the report must be easy to read, have a flow and not cause any discomfort, confusion of frustration.
Having incomplete sentences, spelling mistakes, mis-punctuation, and indirect references does not allow for easy reading, as the reader is constantly in a hunt to “make sense” and eventually ends up reading whatever their mind collates, or worse, might give up reading the report altogether.
Not showing figure legends, starting an answer with a figure, having mismatching legends and captions (e.g. text… placement of Figure 1. More text… as you see in Figure 2…), leaves the reader frustrated, reading back and forth to make sure they did not miss anything. Similarly, in the case where a figure is shown in the report but it is not discussed anywhere in it, the natural question “why did you include the figure and what am I supposed to understand from it?” arises and leaves a frustrated feeling of incompleteness. Figures, tables and graphs are supposed to offer extra or supporting information to arguments discussed in the main body. If you do not make a connection between the figure and its meaning for the report, why include in the first place?
Not explaining acronyms and abbreviations is also frustrating, as those terms clearly mean something to the author and might be of importance for the information presented and the conclusions drawn. However, if the reader is not familiar with these specific terminologies, they will not understand those abbreviations, leading to –guess what– more frustration and the possibility of misunderstanding important information or connections.
In technical reports, and actually in all sorts of reports where we are trying to make an argument based on publicly available data, it is crucial to include the sources of the public information we use. Furthermore, it is important to show the source as close to the information we refer to as possible, rather than have a list of 50 references at the end of the report and have the reader wondering which one corresponds to the argument they found interesting.
I do not think I need to provide an in-depth explanation on why oral speech practices should be avoided in technical writing. Giving an one-liner answer, written work will still be there the next day when oral discussions might be possible forgotten.
In conclusion, the author should make the life of the reader easier, since the task of the reader to understand, interpret and possibly take action on the technical content of the report is already enough. The added difficulty and stress caused from a “not so technical” technical report should be eliminated.
How to avoid those mistakes and improve technical writing skills
Great, major mistakes and areas for improvement are spotted, now it is time to see how we can write things better. The most important piece of advice is to read the report again before pressing the “cannot go back now” submit or send button. Repeat after me: re-reading is required. Reading a piece of written work again and again can make us notice small mistakes, text anomalies, incomplete sentences. Also, the various available tools for spell check can prove to be very handy, especially if English (or whatever language the report is written in) is not the author’s primary language. I noticed recently that Word has an added editing feature that provides syntax advice, on top of the well-known spell check. However, going to the very extreme of reading the report one too many times can lead to apathy in noticing anything “suspicious”. In these cases, having someone unrelated to the topic read through our report can be very helpful. Someone who does not understand the technical concept will focus more on the linguistics and whether sentences “make sense”. They can also point out all the abbreviations or very technical terms that might need to be explained in an abbreviation list or glossary.
Another trick to make sure the report looks consistent and it is easy to read is to zoom out and view the report from a distance, in “multiple pages” format. In this way, it is easier to point out big formatting inconsistencies, such as “orphaned” headings, clustered figures, block text areas, absence of legends, use of different fronts, presentation of headings and sub-headings. Correcting these mainly aesthetic mistakes can make a big difference for the reader. Being on the bandwagon of consistency, it is very easy to make a decision about the format of the legends and apply it on every legend in the report. Having said that, it is also very easy to use cross-referencing tools when referring to a figure or a table in the main body of the report. This practice can make sure that the discussion is around the correct article. The only point of attention is to keep updating and refreshing the cross-referenced items, especially if during writing figures and tables are being added, removed, or moved around.
For areas in a technical report where information can be presented in a list, do so. Avoid big block text areas with very short sentences which could be much better presented in a list. Use of bullet points or numbers is much easier on the eye and gives a sense of continuation. They are also easy to read through quickly and authors can get away with not super structured sentences (in some cases only showing important words might be enough). The best argument of all: readers love them, because they cut down reading time and allow for easy absorption of information. Having said that, when making list you should make sure there is syntactical continuity, meaning that any single point can be a syntactically correct continuation of the original sentence.
Moving to a very dear point of mine, a good technical report should have correct referencing. As it was pointed out
earlier, it is of great importance to present references alongside relevant arguments or data in a report. The author should make sure to use appropriate sources for information and reference them properly, with adequate in-text citations. Information found in sources such as any website ending in -pedia, blogs, or other not peer-reviewed sources should not be present in a technical report. These sources are untrustworthy and not appropriate sources, because anyone can have written anything without any evaluation of the information. There are many formats for referencing, some used more commonly than others. All sources should be referenced and cited with the same format, regardless of which one is chosen, as long as it provides all the necessary information for the reader to retrieve the specific source. Last but not least, finding information online, does not immediately make the source an online source. It could be a scientific paper, a book, a governmental report or even a thesis, and it should be cited as such.
Another important aspect of a technical report is use of technical language. It might sound obvious, but surprisingly enough it is not, especially among undergraduate or early postgraduate students. Use of appropriate terminologies is recommended, rather than referring to technical terms with wrong, inconsistent or indirect wording. Informalities and everyday colloquial terms should be avoided. The aim of a technical report is not to make laymen understand, but to convey specific information on technical subjects, among stakeholders who have a basic understanding of the specific sector.
Last but definitely not least, although there are no set guidelines, I believe that there are certain sections that should be followed in every technical report. Starting with a table of contents, and potentially one for figures and tables. In some cases, when we read technical reports we are only interested in one section or subsection, or scattered sections throughout. Why should the reader have to go through the whole document looking for the needed information while the author could save them some time by pointing out the sections at the beginning of the report? Similarly, having an introductory sentence or paragraph for each section that can give a quick summary of the section can be very helpful. Instead of meticulously reading the whole report, a reader might skim it through using these “introductory paragraphs”, focusing only in areas of interest. Ideally there should be a concluding sentence or small paragraph for the same reason.
There you have it, my easy advice on how to improve your technical writing skills, based on personal experience in writing technical, semi-technical and definitely not technical documents, academic expectations and 50 or so reports, which “could have been more technical”. In a nutshell, make sure there is consistency and structure in your technical reports, read again what you wrote and put yourself in the shoes –or rather the eyes– of your readers.