How do you explain a ‘difficult’ technical subject to someone without any technical background? How do you write a manual that is acually being used? How do you capture business-critical information in such a way that your own employees – or their successors – will benefit from it? Or in general: technical writing – how to do that?
When I explain what I do as a technical writer, the response is often: “ah, user manuals” or “so you’re writing in laymen’s terms”. But that’s only partly true. Manuals and instructions are just a small fraction of all the technical documentation I provide to facilitate working with technical equipment, processes and software – or technical writing in brief. And it’s totally different from laymen’s terms …
No laymen’s terms, but tailor-made
Technical writing is something that you do for a specific target group, and you adapt your way of writing accordingly. This is what I show in the scheme below. When a company hires me for ‘technical writing’, I always have three possible target groups in mind: newcomers, current users and own employees. For instance, the current users (of products, services or software that the company provides) will benefit from everything they need to ‘learn to work with it’: from user manuals in order to get going, up to online help in the case of problems. But as a company you would also like to get future users or newcomers to become interested in what you are really doing: ‘communicate that it exists’. For example by writing articles in trade journals about new technical developments within the company, or white papers to describe factual features and advantages of a certain product to interest a potential buyer. Then there is a third group: the own employees of the company. When employees leave, for the continuity of that company it is not convenient – to put it mildly – that all the knowledge and experience drains away with them. You can prevent this by capturing all business-critical information in an accessible way for a next generation.
Technical writing is not the same as writing in laymen’s terms. Indeed, it’s tailor-made writing. Be aware for whom you write!
Translation
When technical people communicate with each other, they have a certain common background, and they speak the same language. This is extremely convenient, since it is a very efficient way to exchange thoughts with other like-minded people. However, if you would like to inform non-technical people about what is going on – (future) users of your product, but also your own employees without a technical background – you will have to make some kind of translation first. Don’t use professional jargon, but understandable language and clear formulations instead, with a lot of explanation and some examples. And write in correct English, as the document is a showpiece which gives an impression of your company.
So translation ‘from difficult to understandable’ is part of technical writing. But that also holds for translation in the literal sense, from one language to another. Indeed, translating an existing foreign user manual into (my native) Dutch language is a way to facilitate working with technical equipment, simply by translating the manual from ‘difficult’ English into ‘understandable’ Dutch. Or the other way around, by giving greater publicity to a Dutch subject by translating the technical text in question from Dutch into English.
Tips ‘n’ tricks
The need for people that are able to translate a ‘difficult’ technical subject into easily manageable chunks remains as great as ever. I notice this from requests that I get personally, but also by reading job openings for technical writers or authors that pass by regularly. In order to avoid reinventing the wheel, below – and in fact also above – I give some tips that have helped me in doing my work. Sometimes stating the obvious, whether or not ‘a trick from the book’, but often an eye-opener for people who encounter this matter for the first time. Of course it is up to the reader of this article to follow these tips …
Before you start writing …
… think for whom you write, and what is the message. Do you want to explain a technical research result to a large audience? Or is it about a specific product that has to be put into operation, and where a stepwise instruction is needed?
Indicate point by point what you would like to write about, and keep focussing on the central theme of the message. Then have a look what information is already available. Sometimes, that may be more than you think! For instance, the information from an existing white paper can be used with a few or no modifications for a publication in a trade journal.
Fill in the point-by-point list with existing information, after which it is clear what you still have to produce. Such a writing process is also a good moment to update existing and potentially outdated information.
Start with an example
If you would like to introduce a new technical development to other people, the best thing to do is taking an example as a starting point. This is something that you can visualise, and with that as a basis it will be easier to understand a new subject. Apparently, the first three sentences of this article were tempting enough to read up to here …
To illustrate this, I started writing an article on electromagnetic interference between electronic components around 2011 by describing a phenomenon that was well-known in those days:
Picture this … your mobile phone is lying on your desk, close to the speaker of your desktop computer system. A few seconds before you receive a call or SMS message on your mobile phone, the speaker makes a buzzing noise. Is this clairvoyance of the speaker? No way. Here, the wire to the speaker acts like an antenna that picks up and amplifies the signal it receives from the mobile phone network. This is a typical example of electromagnetic interference between electronic components, and it shows that electromagnetic fields are all around us.
Know what you’re writing about
This may seem like stating the obvious, but there is a deeper meaning behind this. In my opinion, you have to understand technical matters ‘behind the decimal point’ in order to be able to explain them ‘in whole numbers’ to other people. When you know your audience, you know what you can and cannot write down. But there is a pitfall. When you know a lot about a certain subject, you may be too familiar with it. And, in your enthusiasm, perhaps you like to write down everything you know about it, which makes it hard to distinguish essentials from side-issues …
Extensive vs. concise
If you would like to introduce a new technology to a newcomer, you can do this quite extensive: start with an example – taking something well-known as a starting point – and then go more in-depth in a narrative way, to explain the reader the features of the technology, and why it’s being used. For instructions, the opposite is the case: use a list with numbered commands – ‘do this, do that’ – and write concise and to-the-point. For computer algorithms – instructions not meant for people but for the computer – it goes even further. Besides to-the-point, these instructions also have to be written without errors, in order to avoid crashing of the computer or running in an infinite loop.
Avoid large text blocks, and use pictures
No matter how well a text has been written … a sheet with only letters is not appealing to read. It becomes more attractive if you present the text in separate blocks with a heading. But pictures are a true added value. So put at least one picture on each page; this also holds for scrollable web pages. Pictures or schemes give a welcome relief. People are visually oriented, and a picture can show immediately how something works – which would otherwise require a lot of words to explain. Moreover, a picture crosses all linguistic borders, making it useful in multiple languages.
Capture in-company information
For a self-employed person, a knowledge management system is not really necessary. The knowledge is ‘inside your head’ or is structured inside your own computer. For larger organisations, there are systems to manage and control in-company knowledge. Besides text, you can capture in-company information increasingly easy as images – supported by developments in ICT. Nowadays it is quite easy to make small films yourself. Any good smartphone is a film camera, and the storage of these films on a hard disk costs virtually nothing. Please consider a decent management system: you can search text pretty well using a good search function, but that is not so easy with pictures or films. A solution might be to include the subject in the file name, or to add key words (‘tags’) to the film. If necessary, you can write out the contents of the film, but that is quite laborious.
Let someone else read the (preliminary) result
Preferably by someone from the target group, and observe the response of this ‘test subject’. For documents that are meant for newcomers: does (s)he really understand the matter? Does the intended message come across? Has the amount of professional jargon been reduced to an acceptable level? For a manual: have him or her conducted the instructions step by step, and watch the result. You will be surprised how an instruction ‘that can be interpreted in only one way’, indeed is multi-interpretable in the real world …
Eddy Brinkman has a technical background, and he is well acquainted with chemical engineering, materials science and information technology. As a technical writer, he helps technical companies to market their own (new, expensive or complicated) technology by writing about it in the English and Dutch language.