Posts Tagged ‘Writing’

Writing about new product features

Posted in Writing on April 20th, 2011 by Jenny – Be the first to comment

Spring LettucesWriting about new product features can be hard work, much like digging the garden to prepare for planting vegetables in Spring.

Often technical writers are called in at the last minute to write about a feature that has taken months of development effort and has a specification document running to 100 pages or more. And the release is going out tomorrow!

I first heard about the gardening analogy to writing from Diana Gabaldon, author of the award-winning Outlander novels, and generous supporter and mentor of writers all over the world.

Diana’s advice to writers is to dig where the dirt is loosest. In fiction writing, that means finding a scene or image that you can see clearly, and starting your writing there. But you can apply this same advice to writing technical documents. Find the easiest section to write and start there.

For example, I work for a company that develops an enterprise software application, and so I’m often called on to document new features based on a specification document (Spec). Specs are written so that the developers know what the new feature is supposed to do and how it should be implemented, so they can be extremely technical and difficult to understand. I’m lucky that my manager understands the importance of good Specs. Every year or so, she gives us the opportunity to re-exam the Spec to make sure it provides us with the information we need.

In my case, the Specs follow a template with the following headings:

  • Enhancement Objective
  • Requirements
  • Functional Solution
  • Administration/Setup
  • Detailed Design

My enhancement document also uses a template, but since my document is for our customers, the information I need to provide is similar but in a different order – an order that will make sense to the customer.

The template I use for the enhancement document has the following headings:

  • Purpose
  • What is contained in this enhancement
  • Administration
  • New behavior
  • End user instructions

As you can see, these sections don’t exactly match the sections in the Spec. And this is NOT the order I use for writing about the feature. Instead, I dig where the dirt is loosest.

1. Purpose

I like to start with a sentence or two, taken from the Objective statement in the Spec. By writing this first, I now understand what the new feature is supposed to do.

2. Administration

Usually the Spec clearly states what administration and setup the user needs to do before they can use the feature. This is also an easy place to start digging, I mean writing. By the time I’ve finished this section I understand a little more about the new feature, I know if there are any new screens or dialog boxes, and I know enough to write the next section.

3. New behavior

In this section, I write about existing features that have changed to support the new feature. This information is included in the Functional Solution of the Spec. I copy the relevant sections from the Spec, rewrite it to use the present tense and active voice, and include screenshots from our test environment.

4. End user instructions

By now I’m much more familiar with the new feature and I can easily write about the new screens and how a user would use them. I include specific tasks and screenshots with examples.

5. What is contained in the enhancement

Having written all the other sections of the enhancement document, I can quickly write a bulleted list to summarize the changes and new features included in the enhancement.

6. Final review

Once I’ve completed the enhancement document, I read through the Requirements section of the Spec to double-check that the new feature does meet the requirements, and that I have documented the new feature and setup correctly. If the Spec is well-written, I shouldn’t need to review this section, but it’s always helpful to the team for one more person to double-check that we are delivering a feature that meets the requirements.

Obviously this approach won’t work in every situation. If the product you’re documenting is not an enterprise application, a new feature might not require any administration or setup before it can be used. Or if you’re working in an Agile development environment, you might not be using Specs at all. But the main idea is to look at the information you have, and start with the easiest section. As you work through, from easy to more difficult, you accumulate knowledge about the feature and build on what you know, so that you’re better prepared when you get to the difficult sections.

This works for me, but perhaps you have a different approach? Do you have a more efficient way of documenting a new feature? Leave a comment, so we can all learn from your experience!

If you liked this post, consider subscribing to my RSS feed. Or have posts delivered via email. Thanks for visiting!

Photo via Flickr user thegardenbuzz


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


5 tips for facing the blank page

Posted in Writing on January 14th, 2011 by Jenny – 1 Comment

Blank Moleskine PagesLike other writing professionals, as a technical writer, I’m often faced with a blank page.

Starting a new documentation project can be daunting, overwhelming, even scary, because not only do I want to provide my readers with good content that answers their questions, I want it to be perfect.

But as soon as I whisper that word “perfect” to myself, I’m in trouble. My brain shuts down and I’m paralyzed, unable to start.

To avoid this paralysis, I’ve learned a few tricks:

1. Find a sample

The first thing I do is find a sample of a similar piece of documentation so that I can start to develop a picture in my mind of what the completed project might look like. For me, it’s critical to have a big picture view before I break the project into smaller tasks. So where do I get these samples? Often the client can provide samples from previous projects. Otherwise, I search online for documentation for similar products from competitors. Once I have a few samples, I review them to see what I think works and what doesn’t. I’m not suggesting copying competitor documentation wholesale, just reading it for ideas to get you started.

2. Build a mindmap

I used to be a complete skeptic about mindmapping. When I was first introduced to the idea, I thought it was just an excuse to buy color pencils and waste time. But after trying it myself, I’m now convinced it’s an effective way of brainstorming and seeing connections between ideas. How can it help a technical writer? A good way to start a new project is to write down everything you know about the product. For example, if you’re writing a user guide for a new camera, draw a mindmap with all the camera features and any other information you think should be included. Then look over the mindmap and see if any of the ideas are related or can be grouped. You can also use a mindmap to see where you are missing information. The form of the mindmap can highlight things you might not see in another format such as a list or outline.

3. Write an outline

Once you have a good idea of what you want to include in your document, it’s time to structure the content. Before I start writing a user guide I always create an outline and have it reviewed by the client. This ensures that the client and I come to an agreement about what will and will not be included in the document. It’s also another chance to find out from the client if I’m missing any information or misunderstanding something. The outline also helps me to break the content into smaller, more manageable pieces, so that I can focus on one topic at a time.

4. Start with the easiest topic

Others might disagree with me, but I prefer to start with the easiest topics first. I find this gives me some momentum and helps me become more familiar with the material. That way when I get to the harder topics I have some background knowledge.

5. Set the timer

I can’t say it too many times. Set yourself a manageable time goal. 25 minutes works for me, but it you can only manage 5 or 10 minutes of focused attention, start with that. The trick is to do a small amount, small enough that you know you can do it without reverting to the perfectionist paralysis.

So tell me, what tricks do you have for facing the blank page?

Photo via Flickr user Sembazuru