Procedures are the meat and potatoes of technical writing. They help users get the job done. Follow these tips for writing clear and useful procedures that your users will appreciate.
Fill in the holes - Ask yourself if your existing procedures cover all of the tasks users need to complete. You may be missing a few, especially if features have been added to your product. If you have a set of well written FAQs (and you should!), make sure there are procedures for addressing the details of each FAQ.
State the goal - Unless it is already obvious, begin by telling users the reason for performing the procedure, and in what conditions it is applicable.
Break it down - Lengthy procedures are harder to follow. Break these behemoths down into smaller chunks and use hyperlinks to guide users from one granular task to the next. Aim for 10 steps or less in each procedure.
Photo by Annie Spratt on Unsplash
Don't assume - Read carefully through your procedures and ask, "Is there anything a user would need to know that I've left out?" Don't assume that users know everything you know about the product. Technical writing is all about acting as a user advocate.
Use warnings - For each step in your procedures, carefully consider whether there are any potential risks or dangers that you haven't documented. A good technical writer will put user safety first.
Link related procedures - Whenever possible, especially in help, use cross-references to point users to related procedures. Most users need to perform multiple related tasks in order to complete their goals. For example, a procedure about using the Print Preview function in your software should be linked to procedures for the Print function.
Tell users what to expect - Consider whether the results of each step need to be documented. Good candidates are those that result in changes in the state of the product (e.g. an important prompt appears in the software, or the blades on the lawnmower begin to turn). Your description of the result should immediately follow the instructions for that step.
Watch for branches - Often a step in a procedure can have multiple results. If your procedure branches, consider making each branch a separate procedure. Use links or cross-references to guide users through.
Combine small steps - Usually it is best to write only one instruction per numbered step. However, small steps can often be combined. For example, "Click the save button" and "Close the application" can be combined into "Click the save button and close the application." Combine multiple small steps only when the concepts are simple enough for users to think of them as one.
Give users an overview - Use a flowchart, list of links, or other visual cue to help users see how procedures are related. This will provide users with an overview to guide them through a complex series of tasks.
Follow up with results - At the end of the procedure, clearly describe the results so that users can assess whether they were successful in completing the task. The more complicated the task, the more assurance users will need. Good technical writing should leave users feeling comfortable about their experience with the product.