Writing technical information for novices sounds easy, but it can be a real challenge when you have expert knowledge of a subject. It’s easy to take it for granted that everybody will have the same understanding as you do. However, this is a problem when you need to transfer your knowledge quickly and could mean the time you spend collating and sharing information is wasted.
Whether you need to put together a technical publication, write content for a website or create a presentation, it’s important to take into account your target audience’s level of understanding. In this article, we’ll look at some ways you can put yourself in their shoes and ensure the transfer of knowledge is efficient, fast and memorable.
Know Your Audience
Before you put a single word to paper, it’s important that you have a firm understanding of your target audience and who the typical user of the information will be. Do they have any basic knowledge of the topic? What will the reader of your document be required to do with the information?
Develop Your Objectives
Once you know your audience, it’s time to define your objectives. The objectives usually fall within one of two categories: reference-based and task-based. Reference-based documents are written from the perspective of what the software or hardware does, while task-based information gives users instructions on how they should use it.
Writing That Anybody Can Understand
When you are writing for novice users, it’s important that they can pick up your document and jump straight in without any other reference material or the need to ask questions. Even the smallest amount of ambiguity can cause huge delays. Try to imagine you are somebody coming to the subject completely cold — and write accordingly.
Jargon is usually a big stumbling block for novices. Providing a glossary of terms or clear descriptions of technical terms or instructions in plain English can solve this problem. Some examples of software jargon might include:
“Flush your browser cache” – Novice users may know what a browser is, but using technical terms such as “cache” and “flush” may confuse them. Explain what the terms are before you instruct users how to perform the operation so they know exactly what they are doing and why.
In this case you can explain what flushing the browser cache means by using simpler terminology such as “delete all instances of website addresses from your hard drive so that they are retrieved directly from the Internet instead”. You can then provide the user with clear instructions on how to do that.
“Run a script” – You may run scripts several times a day and even have automated processes that run your scripts for you. For novices, though, you’ll need to explain what a script is, what its function is, and provide step-by-step instructions on how to execute the script manually.
“Reset the device” – With so many devices in operation across an organization, it is important to be as specific as possible with instructions. A user may know how to use their device to a basic degree, but may not know what “reset the device” means. Also, resetting could apply to a number of scenarios such as switching the device off and on, restoring factory settings or resetting specific parameters on the device.
Instead, provide step by step instructions that are easy to follow and action. You may need to write separate instructions for specific devices if a number of different models are in use.
“Execute the program” – Executing, or opening a program could be as simple as double-clicking an icon on the desktop, but the user may not necessarily know this. Give clearer instructions that show the user what the icon looks like, what they will need to do to open the software, and include any other information that may assist the user. Examples of additional information may include the expected time it takes for the software to open and any popup screens the user may need to action before the software is ready to use.
“Check your resolution” – Fortunately, thanks to responsive design, most software automatically adjusts screen resolution to its physical device environment. However, there are some instances when you might need to instruct a user to change their resolution settings for the best experience. A step-by-step approach with screenshots is essential here, and you may need to create separate instructions for different operating systems.
When you use technical terms in your line of work every day, it can be challenging to break these terms down into words everybody can understand. Fortunately, there are a number of website resources that can assist.
Testing Your Documentation
Before your document is released, it is wise to test it across a cross-section of users that represents your wider audience. This will help you to iron out any ambiguous or complex terms that cause confusion to ensure your document achieves its end goal, whether that is to impart knowledge or achieve a set task.
Technical information can be dry at the best of times, but when it’s also confusing, you risk losing the audience you worked so hard to educate and inform. Taking the time to keep instructions as concise as possible, translate jargon and define the unfamiliar will ensure you transfer your knowledge in the most effective and efficient way.