Posts Tagged ‘Professional development’

Recipe for writing a task

Posted in For new technical writers on March 2nd, 2011 by Jenny – Be the first to comment

zeleninkaA 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 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


Tips for staying current as a technical writer

Posted in Professional development on December 21st, 2010 by Jenny – Be the first to comment

Staying current is one of the most important things you can do as a contract technical writer.

If you know the latest tools and technologies, or at least know of them and can learn quickly, you’re much more valuable as a contractor. And being “in the know” is fun!

Here are some of the ways I stay current:

1. Read widely.

I love reading – fiction, non-fiction, newspapers, magazines, Weet-Bix packets. But also the instructions that come with the things I buy, such as the printer, camera, and food processor. Anything that exposes me to new ideas or ways of doing things. Reading widely also gives me interesting things to talk about with clients, which makes me memorable, and more likely to get the next project.

2. Take online classes and webinars.

The internet has become the world’s largest classroom, offering a wealth of free learning opportunities. You can learn about the specific tools you use. For example, I’m a regular user of Flare, and discovered that MadCap provide free webinars and demos online. Or you can attend webinars about emerging technologies. I recently attended one by Aptara on the creation of ebooks. Look around. You’ll be surprised at what you can find for free or a nominal fee.

3. Subscribe to blogs.

Obviously blogs are a great way to find out what other technical writers are doing. Tom Johnson writes a popular blog called I’d Rather Be Writing. I also like to read blogs about writing, marketing, productivity, and technology. Lifehacker is one of my favorites for hearing about new software.

4. Participate in networking groups and forums.

Networking groups are an invaluable source of information. These can be groups you join online, such as groups on LinkedIn, or local groups that you meet for coffee. I admit I’m a bit of a lurker when it comes to groups online, but even if you don’t join in the conversation, you can learn so much by listening in. Locally, our tech writers group meets about once a month, and we exchange stories about our current projects, challenges we’re facing, and opportunities.

5. Sign up for continuing education classes.

As well as staying on top of the tools, I think it’s important to continue working on your writing. Taking writing classes through the local university keeps my writing fresh, and gives me the chance to meet other local writers. Of course, writing is just one subject of many. If you’d rather try something different, like woodworking, go for it!

6. Attend conferences.

If you’ve never been to a professional conference, I can highly recommend them. With sessions on new tools, processes, and ways they’ve been implemented – you can’t go wrong. And conferences are a great way to grow your network.

How do you stay current?

Photo via Flickr user charmaineharrison3105