Professional and Technical Writing/Instructions
Writing Technical Instructions
Many people are used to following written instruction, but most have never written instructions for another person or audience. In potential careers you may have to write instructions. While some may be short and brief, other instructions could potentially be longer and take great thought to complete them. For this reason it is important to know how to write a persuadable and usable set of instructions. Writing usable instructions can be difficult due to the fact that people read and comprehend things differently. There are people who are visual learners and using written instructions may pose many problems. Keeping that in mind, as well as the fact that the readers will have all educational backgrounds and various learning styles, will enable you to write comprehensive instructions for everyone. It is important to convey the facts, but in such a manner that all types of readers will understand them. The information in this section will give you advice and guide you in your writing process.
Important Points When Writing Instructions
Being persuasive and ensuring that your instructions are usable are two of the most important qualities of a successful set of instructions. You can use these five guidelines to write the most successful and effective set of instructions.
Concise and Clear: People cannot use your instructions if they cannot understand what you are trying to convey. It is important to use common terminology whenever it is possible, and if you must use unfamiliar words, be sure to be descriptive and explain thoroughly. Stay away from long and wordy sentences that are hard to decipher. Keep sentences short and understandable. If you make your instructions too lengthy, your reader may deviate or forfeit due to frustration. Also, try to avoid the use of slang or phrase words. These might mean something different to different people or cultures.
Know Your Audience An effective set of instructions needs to be tailored to its specific and intended audience. This is not to say that an audience cannot be broad or inexperienced, but your set of instructions for example, professionals at the workplace, where common knowledge is quite different from the general public, who can is not familiar with the professional verbiage. Never make assumptions about education level. Be sure to choose your audience before drafting instructions. Always remember to keep your audience in mind when writing a new set of instructions.
Add Graphical Elements: Pictures speak louder than words. Adding graphics to convey your thoughts may be more effective than the words themselves. Instructions that are well illustrated and accompany your written instructions are usually highly successful. It adds an extra level of understanding and allows the reader to skim or troubleshoot if problems occur. Pictures add an additional dimension that will allow your reader to visualize the end product. Also, when using graphics you should be mindful of those visual learners, and adapt the graphics.
Although pictures are great, you must be cautious not to include photographs or illustrations that are confusing or not associated with the actual written instructions. If you pair a poor picture with your instructions, you might cause the reader stress when trying to decipher what you mean.
Also, when taking pictures, ensure that the area is well lit and the pictures are clear and bright. Dark or fuzzy pictures are often difficult to follow. Take care to photograph the subject in the same orientation each time to avoid confusion and consider using a tripod.
Size is also important when using images in instructions. A picture that is too small to see is just as useless as a blurry image.
To be powerful and understandable, your text and graphic for each step should clearly correlate to that step of the instructions.
Design Your Page: Remember that the readers will actually be performing the task as they read along with the instructions. So you should not use solid blocks of small, hard to decipher text. Make sure to create a design and layout for your instructions page that will allow easy readability and add aesthetic quality. Keeping the page simple, but with a defined hierarchy, will assist the reader in completing the steps of the instructions.
When designing your page, a solid hierarchy is important for scan-ability. The use of bold headings, italics, and roman numerals will aid the reader in finding their place easily and helps with the overall visual appearance.
Create a Flow: It is important your instructions be planned out in a logical progression. Make sure to state the problem clearly on the first page. Follow your problems with a set of specific steps detailing how to solve the proposed problem. Technical instructions must flow in a logical pattern. For example, when assembling a table it would not be good if you put the finishing touches on it before you had all the screws in place. As stated before, there should also be clear graphics where necessary to clarify the action. Remember, a picture is worth a thousand words.
Test Your Instructions: We all know that instructions are difficult to write and that sometimes it sounds good on paper, but when you actually attempt to put the instructions to use, you might find that your wording makes no sense to others. Remember what might be common or obvious to you might baffle your readers, so know your audience. In addition to testing your instructions on yourself, have someone who knows nothing about your product test it. This is called a usability study. Take notes on what worked and what didn't and then revise your instructions accordingly. In the long run the more people that test your instructions, the more effective the final set will be.
Tailoring Instructions to the Intended Audience
Tailoring your instructions to the intended audience can be one of the most difficult tasks of your writing process. Before you begin your writing process you need to identify who your audience will be and how you can tailor your instructions to make them as understandable as possible. To help you do this there are several questions you can ask yourself:
- What background might your audience members have and what prior knowledge might they possess? This will help you to determine what you will need to include or not include in your instructions.
- What will their needs/interests be?
- How will their demographics affect how you write? If the majority of your audience comes from a different demographic than you, you need to take into consideration language issues and make sure graphics are clear.
- Is there a variability in your audience? If your audiences are composed of people with varied backgrounds, your writing should tailored to the majority of your audience and you may also consider adding additional information in appendices.
Based on your answers to the above questions, there are several ways you can insure that your instructions will be as clear as possible to your readers.
- Add information (such as tips, side notes) the readers will need in order to understand your instructions and make sure no key information is missing.
- Do not add information that is unnecessary; it may confuse or mislead your readers.
- Make sure the document is at the level of your audience.
- Add examples/graphics. Graphics can be very helpful to a reader.
- Have a clear organization. Lack of organization creates confusion and frustration.
Writing Your Instructions
The following sections are descriptions of the different parts of the general superstructure of a set of instructions. What sections to include will vary based on the complexity of the instructions. Your document may contain any of the following sections:
- Description of Equipment
- Materials and Equipment Necessary
- The procedures
- Visual aids
What is included in your introduction will depend on what your instructions are for and who will be using them. In any case, the introduction should be brief, but still informative. The introduction can include any or all of the following sections:
- Subject/Aim: Here you should indicate the specific task that will be explained and what the outcome of the procedure will be.
- Intended Readers: You may want to identify who the intended readers of the instructions are and if the reader will need additional knowledge or background in order to complete the task.
- Scope: This will help the reader to know if the instructions will help them complete the task they want to or not.
- Organization: Giving the reader an overview of what the rest of the instructions will look like can help them to more easily understand them. This section could also go under scope.
- Safety: It is your responsibility to inform the readers of any hazards or dangers that could occur while they are completing the task. You need to display warnings in a clear and understandable fashion.
Description of Equipment
If there is equipment that the reader will have to use in order to operate or repair a piece of equipment, you may want to include a description of it.
Provide a list of equipment that the reader will need to accomplish the task so they know if they need additional tools or things they may not normally have. A list of supplies is also helpful for a reader to make sure that they have all the parts and pieces they need.
This section is obviously the most important part of an instructions set since it is the actual steps that the reader will follow to complete the task at hand. There are many ways to format the procedures, but most are done with numbered lists. The following are things you should do to make the steps clear and concise:
- Write each step with concise wording so it is easily understood and completed.
- Give readers enough information to perform the step, avoid redundancy.
- Put the steps in a list. Numbering often works the best.
- Highlight key words.
- Make sure the reader can locate steps quickly and easily.
- Number steps.
- Skip lines between steps.
- Make actions stand out from the rest of the text.
- Tell the reader what to do if they make a mistake. Not knowing what to do will cause frustration and the reader may give up on the task.
The use of graphics and pictures to correspond to each step is highly recommended. Each person has different learning habits; some like texts while others are better off with pictures. The presence of graphics also allows the reader to make sure he/she is still on the right track. In most situations it would be beneficial to have a combination of both graphics and words.
Instructions should include this section to tell the reader what to do if something goes wrong during the building process or if the completed project does not look like the expected outcome. Putting this information into a table format often works the best.
For an example set of instructions visit page This webpage contains information from the textbook entitled Power Tools for Technical Communication by David A. McMurrey.
Usability testing is an absolutely crucial step in preparing an effective set of instructions. Once you have completed a draft of your instructions, it is important to test them to see where improvements can be made. A usability test should be performed on multiple testers for each updated draft of your instructions. Here is how you go about performing a usability testing:
1. First, you should choose your testers from a group that is representative of your intended audience. In order to single these specific users out, you may need to ask a few preliminary questions. For example, asking what their experience level with the task is or what their job field is.
2. Next you need to choose how you will evaluate the tester's performance in completing the task. There are different methods to choose from, but one method is called the "Think Aloud" method. When using this method you ask your tester to complete the task using your instructions while verbalizing everything that is going through their head as they go through the instructions. Do not offer any help to the tester as he or she goes through the test, kindly tell them that you can answer their questions at the end. As the tester says what is confusing or hard you take notes. You can record this information in a chart that has three columns. In the first column you will record the problems your tester had. In the second column you write down what the possible cause of each problem was. In the third try to generate a possible solution to the problem or possible ways you can change your instructions to make them more understandable. Be sure to be descriptive in what you want to find out. Be sure to lay out testing form to collect all pertinent information about your testing so no information is overlooked or misplaced.
3. After the test is done look at your notes and ask the tester to elaborate on the problems that you noted. This is an important step because you are getting direct feedback from your audience. Make sure that you understand exactly what was confusing for them, as this will help you in writing the most successful set of instructions. Ask testers how you could change that step or part of the instructions to make them unambiguous.
4. Based on your findings edit and update your instructions. After you do so they should be more understandable and easier to follow for your intended audience. In many cases it is appropriate or even necessary to conduct one or more rounds of usability tests as you perfect your instructions. More testing may prove beneficial in discovering problems that were overlooked the first round of testing or because the problems may have been masked by original complications. If time permits, be sure to run as many rounds of usability testing as needed.
- Note: Pay special attention to your intended audience and ensure that you have the number of testers, and accurate demographics necessary to accurately represent your sample. For example, if you are making instructions for a 'beginner audience' and test an all 'expert' audience your sample will not be representative. In addition, if you are wanting to make instructions for a large audience of several ages, gender and experience level, your sample will need to be large and representative of that population.
- If instructions need tester to use both hands throughout (like tying a tie,) consider making all the instructions visible without turning pages so it is easier for the tester to complete the task.
General Writing Style Tips
Many people resist reading instructions. They try to figure out for themselves how to operate a product or perform a task and will turn to the instructions only if all their efforts fail. When they do read the instructions, they want to understand everything immediately without having to read anything twice. A simple design, plain wording, and clear instructions will be critical to encouraging readers to pay attention to your instructions or procedures.
When writing technical documents and instructions there are several style tips you should keep in mind:
- Use a lot of imperative, command or direct address, kinds of writing. It is OK to use "you" when writing instructions, because you are addressing the reader directly.
- Use active instead of passive voice.
- Do not leave out articles such as a, an and the.
- Use action verbs.
- Ensure graphics match descriptive text to avoid confusion.
- Label graphics by steps, for example Step 17 "...Put...", the graphic should be labeled clearly with a number "17" or if multiple graphics exists for a line of text writing in chronological order "17a, 17b, etc." or if different views "17 front, 17 back, etc."
- Keep text short but descriptive.
- Avoid complicated jargon, use simple verbiage to ensure understanding by a broad spectrum of users.
- Use concise headings and subheadings to describe and highlight each section.
- Leave plenty of white space around headings.
- Highlight safety information and warnings.
- Keep illustrations as simple as possible.