Instructional writing is a common type of technical writing. Incomplete, ambiguous, or badly written instructions can confuse the reader. Similarly, long, and complicated instructions can be difficult to follow.
Audience is key in instructional writing. Who you are writing for determines what to say, how much to say, and how best to say it. A skilled instructional writer can put themselves in the shoes of the user when creating content.
For instructional writing to be effective, the steps must be clear and easy to understand. It is good practice generally to write from the perspective of a new user, and especially so if you are not familiar with the technical knowledge or skill level of your audience.
Here are my top 5 tips on how to write instructions:
Arrange the steps in a task in a logical sequence.
Use short sentences and do not convey more than a single idea in a sentence.
Use appropriate punctuation to make the instructions clear.
Use active voice.
Use imperative tone to avoid any ambiguity.
Tip #1: Arrange the steps in a task in a logical sequence
When documenting a task, arrange the steps in a logical sequence and number the steps.
The sample screenshot below (from the ASCENT learning guide Autodesk Inventor 2023: Advanced Part Modeling) shows how the steps have been arranged in a logical sequence. Note the use of a numbered list for the sequential steps.
Tip #2: Convey a single idea in a sentence
Each step in your instruction should ideally cover only a single action, as shown in the image below. It is best to use short and simple sentences to convey an idea. Also, avoid jargon and complex technical terms wherever you can.
Tip #3: Use punctuation to make instructions clear
Below are two sample sentences to show how punctuation (comma, hyphen, parentheses, period) can be used to make the instruction clear.
Sample 1: In the Model browser, right-click on Solid2 (under the Solid Bodies node) and select Properties.
Sample 2: Check the sample sentence below, and note the use of chevron mark (>) and comma in the recommended.
Not recommended: In the 3D Model tab in the Create panel click (Sweep).
Recommended: In the 3D Model tab>Create panel, click (Sweep).
Tip #4: Use active voice
Try to maintain the same-person perspective throughout the document. That is, if you have been addressing the reader directly (you) when providing instructions, use it consistently throughout the entire document. Do not change it to "one" or "we" or even use passive voice.
For example, in the Autodesk Inventor 2023: Sheet Metal Design learning guide, one of the Practice sections begins with the sentence, "In this practice, you will create Flange features on the edges of a model." In the sentence that follows, you should use "you" (as in the recommended sentence below) and not "we" (as in the not recommended sentence).
Not recommended: In this practice, you will create Flange features on the edges of a model.
Create a Flange on the open space in the part. We can select individual edges or use loop selection and clear edges.
Recommended: In this practice, you will create Flange features on the edges of a model.
Create a Flange on the open space in the part. You can select individual edges or use loop selection and clear edges.
Tip #5: Use an imperative tone and avoid ambiguity
Avoid using the ambiguous modal verb "may" in instructional writing. Instead, use "can" for possibility (such as what the software allows the user to do) and "must" for necessity (such as mandatory steps), if required. But ideally, drop all unnecessary words and be simple and direct in your tone.
Not recommended (grammatical sentence but lacks clarity): After filling in all five fields in the Properties panel, you may click the OK button to save.
Recommended (when you are informing the reader as to what is possible): After filling in all five fields in the Properties panel, you can click the OK button to save.
Recommended (when you are instructing the reader that this is a required step): After filling in all five fields in the Properties panel, you must click the OK button to save.
An even better option is the sentence below where "you must" has been dropped. It essentially conveys the same idea but has the correct tone for an instructional sentence and in fact makes the sentence simpler.
Ideal (when you are instructing the reader that this is a required step): After filling in all five fields in the Properties panel, click the OK button to save.
Have fun creating an ideal set of instructions. 😊
About the AuthorFollow on Linkedin More Content by Surya Nair