How to Use Simple Words in Technical Writing

Explore this Article

parts

1Planning Ahead

2Writing so Everyone Understands

3Using Simple Words

Other Sections

Tips and Warnings

Related Articles

References

Technical writing is considered a form of written communication that includes at least one of the following three items: (1) writing about a very specific and technical subject (e.g. the outcome of a heart surgery); (2) describing how to use technology to do the communication (e.g. websites, blogs, etc.); or (3) documenting a process or procedure (e.g. how to use MS Excel). Technical writing is supposed to take a complex and complicated topic and make it easier to understand and interpret. One way technical writing makes things easier to understand is by using a simple, straight-forward writing style, including simple words.

Steps

Part 1

Part 1 of 3:

Planning Ahead

1. 
   1
   Know who your audience will be. Before embarking on any technical writing project, the first thing you need to ask yourself is who will be the user of your document. Are there more than one type of user? What sort of knowledge and experience will this user have about the topic? What will that user be using my document to do? How often will they need to refer back to my document? Will the user understand the jargon associated with the topic?

   • Users of technical writing can fall into several different categories, each with their own specific needs: customers, end users, installers, developers, trainers and trainees, or tech support.
   • You will most likely not be able to write a separate document for each user, so you will need to take into consideration the needs of ALL potential users when writing.
2. 
   2
   Develop the objectives for your writing. Once you’ve figured out who your audience is, you need to figure out what how those users will be using the document. In general the document’s objective will fall into one of two categories: task-based or reference-based. Task-based documents are from the perspective of what the user is doing, whereas reference-based documents are from the perspective of what the product does.

   • An example of a task-based document could be instructions on how to create a website in Wordpress. In this situation you’d walk the user through all the steps from start to finish, regardless of where those steps occur within the Wordpress software.
   • An example of a reference-based document could be a user’s manual for a Blu-Ray player. In this situation you’d explain each part of the machine separately - what each button, function, menu item, etc., does.
3. 
   3
   Get yourself organized in advance. Planning out your entire writing process is an efficient and effective way to approach your project. A good approach includes: gathering the information, planning and organizing the information, writing, verifying and testing, and redoing and revising. While this approach looks like it has 5 neat steps, it’s actually a circular process. At any point in this approach you may need to go back to a prior step.

   • Gathering the information includes: reading all you can about the topic; using the product yourself; understanding what your user(s) will need to know about the item; interviewing the people who developed the item; attending meetings where the item is discussed in detail and listening to what is said; and allowing the item experts provide you feedback if you got something wrong.
   • Planning and organizing the information includes: figuring out exactly what it is you need to write about (i.e. what are your deliverables); developing a schedule for your work; and reviewing your plan with the necessary people to make sure it meets expectations.
   • Writing is most efficiently accomplished by: creating a complete outline of your document, including all the topics you plan to cover; actually writing out each chapter and section; and determining when you do not have enough information to finish a particular chapter or section and need to do more research.
   • Verifying and testing is where you make sure your document actually does what it was intended to do, accurately. Start by attempting to use your own document - do all the steps make sense, is anything missing, etc. Next read through the document for non-content items like grammar, spelling, format, etc. Finally you’ll need to give your document to one or more experts and ask them to review it.
   • Redoing and revising is where you take all the feedback you’ve received, including from yourself, and update your document with those items. And depending on how the document is going to be used, it can include constant reviews and updates over time, as the document is used and problems are found.
4. 
   4
   Know ahead of time that it’s not going to be perfect. Unfortunately, most technical writers are being paid to produce a document either within a set timeframe, or for a set price. Chances are you may find yourself needing to compromise on one thing in order to ensure something else can happen. This may seem like a harsh idea to get your head around, but it’s an unfortunate reality of a lot of work environments and situations.

   • The most important thing to remember is that a technical document should — first and foremost — be accurate.
   • The document should also be as complete as possible. There shouldn’t be any missing steps that could confuse a user.
   • Once you’ve accomplished the ‘accurate’ and ‘complete’ portions, then you can worry about typos, formatting, tables, lists, etc.
   Advertisement

Part 2

Part 2 of 3:

Writing so Everyone Understands

1. 
   1
   Avoid jargon and slang. At this point you should be fully aware of who your audience is, and if they already have the expertise to understand the technical jargon associated with your topic. If your entire audience consists of expert users, using jargon shouldn’t be a problem. But if your audience consists of anyone who is not an expert user, it is better to avoid the use of jargon as often as possible. Most, if not all, jargon has common words that can be used instead. Some examples of jargon include:

   • “Script” - in a technical sense this refers to computer code, but the average person might think this means a script for a play or movie.
   • “Unsub” - this term is used a lot in crime TV shows and movies. It means an “unknown/unidentified subject.” But to a lay person this term will probably not mean anything.
   • “Due diligence” - in a business sense, this means to do complete research on something in advance of making a decision. It may not mean anything to a lay person, or they may interpret the words individually.
   • “Left wing” or “right wing” - from a political perspective this refers to how liberal or conservative someone is, but a lot of lay people aren’t familiar with the terms. Instead, write out liberal or conservative.
2. 
   2
   Spell out abbreviations and acronyms. When using abbreviations, always spell out the full name first, and then put the abbreviation in brackets after the full description (e.g. American Library Association (ALA)). For the rest of the section or chapter you can use the abbreviation instead of the full name (e.g. ALA).

   • Be aware that acronyms are not necessarily the same thing as abbreviations. Acronyms are letter-only short forms like abbreviations, but unlike abbreviations, the letters can be pronounced like a word. For example, ALA would have each letter pronounced separately when saying it, whereas LAN isn’t spelled out, it’s turned into a word.
3. 
   3
   Define unfamiliar words or terms. There are many scientific or technical terms that you will need to use in your writing, but may be unfamiliar to some or all of your audience. When using a word or term that is not part of everyday language, define it the first time you use it. You can define it by either putting the definition in a set of brackets after the term (e.g. put the definition here), or you can create a glossary that applies to the entire document. If you decide upon a glossary, highlight the word or term in such a way to alert the reader to refer to the glossary for its definition (e.g. bold, italic, underline, etc.).

   • An alternative to a document-wide glossary is a table defining important words and terms at the beginning of each chapter. Users would read the definitions before reading the content. With the definitions fresh in their memory, the content will be more understandable.
   • Avoid using cliches, even if you think the majority of your audience may understand them.
4. 
   4
   Remember that less is more. When trying to explain something technical to the average person, use as few words as possible to get your point across. It is not necessary to explain every last thing you say in immense detail. Remember who your audience is - if you’re writing a user’s manual for a DVD player, you don’t need to explain how the circuit boards inside the DVD player work. You just need to explain what happens when you press a certain button. This suggestion also includes choosing the least number of words necessary to make a point - avoid redundancy.

   • An example of a redundant statement is: “Water quality in the Athabasca River declined in May. This decline occurred because of the heavy rainfall this month. All the extra water overloaded Yellowhead county’s water treatment plant.”
   • The same example written without redundancy is: “Water quality in the Athabasca River declined in March because heavy rainfalls overloaded the Yellowhead Country water treatment plant."
   • Example statements (with needless words in parentheses) are as follows:
     • (already) existing
     • at (the) present (time)
     • (continue to) remain
     • (empty) space
     • mix (together)
     • never (before)
     • start (out)
     • none (at all)
5. 
   5
   Put the key information up front. When making a point in technical writing, put the most important pieces of information first. Once the key information has been stated, then you can follow-up with an explanation of why it happened, or what caused it to happen.

   • Don’t say “Despite five penalties in the first and second periods of the game, the Maple Leafs still managed to win,” when you can say “The Maple Leafs won, despite five penalties in the first and second periods."
6. 
   6
   Add humour. Technical (and scientific) writing isn’t know for its humour, and that’s not necessarily a good thing. Adding a little humour, in just the right place, helps the reader pay attention. Dry, boring and repetitive technical writing tends to lose the reader’s attention rather quickly. One great place to put humour is in examples.
   Advertisement

Part 3

Part 3 of 3:

Using Simple Words

1. 
   1
   Keep it straight-forward. Simple, straight-forward writing, especially in a technical document, helps ensure that the reader doesn’t misunderstand what is being said. This means keeping your explanations and intentions clear. Everything you write should only have one meaning or interpretation. Simple also means using smaller words when possible, rather than large, complex words that don’t help explain the point. Large, complex words can also make the writer seem arrogant and can cause your reader to lose interest.

   • An example of an unclear instruction is: “The system shall free storage space as needed by first in, first out (FIFO) or some other defined priority schedule.”
   • An example of a clear instruction is: “The system will delete oldest recordings first when making space for new recordings."
   • Some examples of complex vs. simple words are as follows:
     • utilization vs. use
     • functionality vs. feature
     • facilitate vs. cause
     • finalize vs. end
     • aforementioned vs. mentioned
     • individualized vs. individual
     • heretofore vs. previous
2. 
   2
   Use an active voice. Using an active voice means that the subject of a sentence (i.e. the noun) performs some sort of action, as opposed to the action being performed on the subject (i.e. passive voice). Active voice also refers to what types of verbs are used. Active voice tends to be easier to understand when read, and sounds more confident.

   • Another way to think about which verbs you use is to consider if they need to be preceded by “to be,” “is,” “was,” “were,” “has been,” and “have been.” If those extra words are required, the verb is probably written in a passive voice and should be rewritten.
   • Passive voice also tends to be written as something that happened in the past, whereas you should write as if everything is happening in the present, right now.
   • An example of a statement with a passive voice: “The man was bitten by the dog."
   • An example of a statement with an active voice: “The dog bit the man."
   • If you’re unsure whether what you’ve written is straight-forward enough, read it out loud to yourself.
3. 
   3
   Avoid abstract nouns. Nouns come in two types - concrete and abstract. Concrete nouns are items you can actually experience with your five senses. For example, stone, DVD player, engine, blue wire, etc. Abstract nouns are items related to emotions, values, qualities, concepts, etc. For example, calm, evil, honesty, maturity, talent, disbelief, love, death, dreams, etc. A technical document should be trying to explain to a reader HOW to do something in a straight-forward and concrete manner. Abstract nouns can end up distracting the reader from the point you’re trying to make.

   • An example of where abstract nouns are used: “The existing nature of Mount St. Helens’ volcanic ash spewer was handled through the applied use of computer modelling capabilities.”
   • An example of where concrete nouns are used: “With Cray computers, we modelled how much ash spewed from Mount St. Helens."
4. 
   4
   Be careful of pronouns. Pronouns like “it” and “this” can end up confusing readers as most statements you write will refer to multiple nouns. A pronoun, in general, has something called an antecedent. The antecedent is the noun that pronoun is referring to. For example: My dog chased the stick and brought it back. The word ‘stick’ is the noun, and ‘it’ is the pronoun. The pronoun ‘it’ is referring to the antecedent ‘sticks.’ Ideally, you should repeat the noun when possible (e.g. my dog chased the stick and brought the stick back), or reword the sentence such that pronoun is not required (e.g. my dog chased and brought back the stick).

   • An example of a statement where pronouns are used: “The monitor needs to be plugged into the computer, it should be close enough for a cable to reach.” What is “it” referring to? The monitor or the computer?
   • An example where pronouns are not used: “The monitor needs to be close enough to the computer so the cable can reach."
5. 
   5
   Use consistency. Technical writing can contain a lot of words that could potentially be written multiple ways. For example, email vs. e-mail. Or, login vs. log in vs. sign in. Which option you choose to use is up to you (or whomever is paying you), but once you pick an option, use it consistently throughout the entire document. Going back and forth between ‘sign in’ and ‘login’ will cause confusion for the reader. Other things to keep consistent are:

   • Starting bulleted lists in the same format every time, and using the same punctuation each time.
   • Capitalizing the same terms throughout the entire document, and deciding which items are to be capitalized.
   • Decide if you’ll use contractions or not, and then stick to it.
   • Decide if you’ll spell out numbers, or only use the actual number. In many technical documents the numbers zero through nine are usually spelled out, whereas any number that is a double digit or more is written as a number.
   • Decide how you’ll use formatting like BOLD, ITALICS and UNDERLINE, and keep it consistent.
6. 
   6
   Be precise. Being precise in technical writing means avoiding vague terms that are unnecessary to get your point across. Words like ‘countless', ‘some', ‘approximately', ‘huge', ‘tiny', etc., are unnecessary in most situations. Specific examples of how to alter your writing in order to be more precise are as follows:

   • Don’t say “There are many replacement parts available out there” when you can just say “Replacement parts are available."
   • Don’t say “A really strong odour was noticeable” when you can say “A pungent smell is noticeable."
   • Don’t say “Using the diagnostic system installed on the main system …” when you can simply say “Using the diagnostic system…” or “Using the diagnostic system onboard the main system…"
   • If there are a specific number associated with what you talking about, use the number when referring to that item, not a high-level phrase. For example, use “There are 10 possible reasons this could happen:” rather than “There are a number of possible reasons this could happen:”.
   Advertisement

Expert Q&A

Search

Add New Question

Ask a Question

200 characters left

Include your email address to get a message when this question is answered.

Submit

Advertisement

Tips

• The Chicago Manual of Style tends to be the go-to source for style guidelines for non-academic writers. Consider purchasing an online subscription to the website, or buying a hard copy of the book, so you’ll always be able to refer to it.
  Thanks

  Helpful0Not Helpful0
• Ideally writers should strive for a distraction-free environment when they’re writing. This means turning off your cell phone, not checking your email, not answering the phone, etc. If you don’t have any distractions, once you start writing you’ll be amazed at how much you can do!
  Thanks

  Helpful0Not Helpful0

Advertisement