A task is one of the fundamental building blocks of good technical writing, and one of the first things new technical writers learn. I was reminded of this when I bought a new cookbook at the end of last year.
In my spare time I love to cook. I have several shelves devoted to cookbooks, and I can spend hours browsing through my books looking for a new recipe to try. One of my favorite cookbooks is Jamie’s America, written by Jamie Oliver, with recipes he created while he toured the United States. There are some fantastic recipes in there. One I particularly like is the Green Chilli – the lime and fresh mint really give it a fresh flavor!
This cookbook does a lot of things well. It has loads of fabulous photos (a necessity for a great cookbook!), fascinating introductions to each recipe, and very tasty recipes. But there is one thing they could have done that would make it perfect: the recipes should have numbered steps.
Instead, the cooking instructions are written in paragraphs, with several steps combined in a single paragraph. What I’ve found, is that even if I read the recipe carefully, I often miss a step or forget an ingredient. The lack of numbering makes it very hard to follow.
Recipes, like all tasks, must be easy to read. So I thought this week I’d share my approach to writing a task.
1. An overview.
Before describing a task, it’s important to give some context. Why would you want to do this task? What is the benefit? What things do you need to be aware of before you do the task? The overview can be as simple as a sentence or two, or it can be a longer paragraph.
2. A heading.
Every task should have a heading. In the case of a cookbook, this would simply be the name of the recipe. But for a technical task, I prefer to use a heading that begins “To…..” This gives the user a simple description of what they can accomplish if they follow the task. For example, if I was writing a task about installing Skype, I’d write a heading “To install Skype:”.
Task headings are particularly useful if you need to write more than one task on a page. Say I wanted to write a topic about “Getting started with Skype”, I might have several tasks on the page – installing Skype, signing up for an account, and logging in for the first time. Each of these tasks would have its own heading.
3. The steps.
Steps tell the user how to do the task. When steps need to be done in a particular order, use a numbered list. When the order is not important, use a bulleted list. A simple task might use just numbers, whereas a more complicated task might use a combination of numbers and bullets. When writing a task, try to use no more than ten steps. If you need more steps, split the task into several smaller tasks. Each step should describe a single action. The simpler you make your task, the easier it is for someone to complete it correctly.
Using Skype as our example, here’s a very simple task:
Getting started with Skype
Skype is a program that lets you to make voice calls over the Internet. You can use Skype to call other Skype users for free, or send instant messages, or you can use it to call landlines and cell phones cheaply.To install Skype:
1. Visit www.skype.com to download Skype.
2. Double-click SkypeSetup.exe.
3. Follow the instructions in the installer.
Next time you’re writing a task, or recipe, remember to check that you’ve given the task some context, given it a heading, and used no more than ten steps.
TIP! I’d suggest writing the title and task first, and the overview afterward. Sometimes when you’re learning about a new feature, it’s easier to focus on the specific steps of the task first, so that by the time you write the introduction you have a better understanding of how to do the task and what it’s used for.
Your turn! Any suggestions for new writers learning to write their first task?
Photo via Flickr user Petr & Bara Ruzicka