Posts Tagged ‘Writing’

Making the most of reviews and critiques

Posted in For new technical writers on July 14th, 2011 by Jenny – 1 Comment

RotoruaIf there’s one thing new technical writers can struggle with, it’s accepting critical feedback from reviewers.

When you’ve labored over a piece of writing, done your best to provide accurate information, kept your end-user in mind, and thought about the document design, it can be difficult to hear that you’ve made mistakes or the customer wants something different.

One of my first assignments as a technical writer was to create a setup poster for a printer. Having a particular love of symmetry, I created a beautiful poster, with two columns of equal widths. When I’d finished it, I took it to my manager. She took one look at it and said, “Yes that’s good, but perhaps you could use three columns instead of two.” Hmmmm, I thought. But I prefer two columns! So I made the other changes she suggested and presented it again. “How about using three columns?” she suggested. And a third time. Finally I did a version with three columns, and she was right. It looked much more balanced and was easier to read. Lesson learned!

Maybe you’re not as stubborn as I used to be, but if you are, here are some simple suggestions for making the most of review comments and critiques.

1. Approach feedback with a good attitude

Remember that reviewers are trying to help you write the best documentation possible. You and your reviewers likely both want the writing to be accurate and clear, so don’t take comments as criticism, and especially don’t take them personally. This can be difficult when reviewers have a penchant for using ALL CAPS. But ultimately, however harsh their comments sound, they really do just want to help.

2. Read all the feedback before you start making changes

When you receive feedback, you might want to dive into your text and make changes right away. Try not to do that. Reviewers can sometimes change their minds as they go, so if you read all the feedback from start to finish, you might find that they mention something early on and then decide it does not need changing by the end of the document.

3. Separate feedback into two types – technical accuracy and personal preference

Sort the feedback so that you can tackle the technical accuracy comments first. If there are disagreements about technical details between reviewers, you’ll want to sort these out before you start making changes to your document.

4. Start with technical accuracy feedback

With technical documents, accuracy is generally more important than writing style, so I recommend addressing technical issues first. If you have written that the software should be installed and then the printer connected to the computer, but actually it should be the other way round, it’s more important to fix the order of the steps than it is to change a wording preference. If the steps are in the wrong order, end-users will have trouble setting up their printer, leading to more support calls, and costing the manufacturer more money.

5. Make the best use of personal preference feedback

Feedback that is more about writing style can also be a real opportunity for you to grow as a writer. Look through the feedback and decide which comments resonate with you. If you immediately agree, then you’ll want to make those changes. But what about the things you don’t agree with? These are things to consider. You can talk to the reviewer and get additional details. This might be enough for you to change your mind and agree to make the change. Or you can discuss why you don’t think the change is a good idea, clarifying your own thinking, and letting the reviewer know that you respect their opinion, but have a good reason not to do as they suggest. Also, you can talk to other technical writers on your team, or discuss it with your manager.

6. Thank your reviewers

Really! Send an email to all the reviewers thanking them for their feedback, or thank them in person next time you bump into them in the hall. Everyone likes to be appreciated for their work, and reviewers are no different.

Your turn. Any tips on dealing with critiques and feedback?


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

Photo via Flickr user mcaretaker


Proofreading tips for lone writers

Posted in Writing on May 18th, 2011 by Jenny – Be the first to comment

"New Zealand" "Lake Tekapo"  "South Island"Once or twice in my career as a technical writer I’ve been lucky enough to work with an editor. But often we technical writers work alone and have to proofread our own writing.

My grandfather was a newspaper editor, so I learned at a young age, that spelling mistakes and grammatical errors were unacceptable. I guess that’s why I have a highly-tuned radar for typos. But I admit I miss things too. Here are a few tricks to help you avoid the embarrassment of poor proofreading:

1. Read the document backwards.

Start with the last paragraph first. Because you’re reading it out of order, you’re more likely to spot the typos and spelling mistakes.

2. Read the document aloud to yourself.

If you haven’t tried this before, you might be surprised. Even muttering it to yourself under your breath works (ignore the looks you get from anyone nearby!)

3. Double-check the headings.

It’s notoriously difficult to catch the mistakes in headings. I look at headings up to five times to be extra sure there are no glaring misspellings.

4. Pay special attention to words that sound the same with different spellings.

Can you imagine my embarrassment at using the wrong spelling for palette?

  • palette – a color palette used in a software application
  • palate – the roof of your mouth
  • pallet – a low platform used in warehouses for storing goods
  • pellet – a small round ball, such as pet food

5. Learn where and where not to put apostrophes.

It’s one of those things we often miss, especially in headings. Apostrophes are used to show possession and to replace letters missing in contractions. If you’re confused, read this simple resource from the Purdue Online Writing Lab.

6. When you think you’re done, read the whole piece through one more time.

Preview your writing and reread the entire thing in the final format. For blog posts, that’s easy – simply preview the post in a browser. For other documents, try generating a PDF (or Help file) and read the document as it will look to your audience.

7. Keep a checklist.

If all else fails, keep a list of the things that are particular issues for you. If you always mix up there/their, put that on your checklist.

Your turn: Do you have any tricks for proofreading your own writing? Leave a comment below.


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

Photo via Flickr user thinboyfatter


Keeping the writing fresh

Posted in Writing on April 27th, 2011 by Jenny – 1 Comment

VegetablesWorking as a technical writer, it’s easy to focus on the tools we use. Learning new tools and implementing new processes is fun and exciting.

But often we have to update the same manuals, write the same documents, produce content using the same branding and styles over and over. And our writing can become dull and lifeless.

I was thinking about this the other day when I was out for dinner. I was eating a salad, picking around some particularly limp lettuce. I wanted to toss this salad in the garbage and make my own. The vegetables in this salad were not fresh.

But there’s a reason I like to eat restaurant salads. It’s because I’m always looking for new ingredients to add to my salads at home. Take jicama, for example. I discovered raw jicama in a salad in California.  In it’s natural state, it’s nondescript, a bit like a wrinkly potato, and does not look very appetizing. But peeled and sliced, it’s sweet and crunchy, and the perfect addition to a fresh salad.

Which brings me to the point about technical writing. How do we do the same thing with our writing? How do we keep it fresh?

1. Look for the cool

When I find myself doing a mental eye roll – oh no, not this again – I know it’s time to step back and take a fresh look at the piece I’m writing. By fresh look, I mean, I look for what’s cool about this new feature. Why would a user want to use the feature? How will the feature help the user? Is there anything about this feature that will make the user say “Wow, cool!”? Once I’ve found that cool thing, the writing seems to flow easily.

2. Look for ways to simplify the writing

One of my goals as a technical writer is to make tricky things easy to understand. One way to do this is to keep the writing simple. Use short sentences. Use short paragraphs. Use the active voice. Use the present tense. Look through the piece of writing you’re working on now. Could you simplify it?

3. Rediscover your passion for writing

Many of us became technical writers because we like to write, but when our writing becomes dull, we can lose interest in the work. To rediscover your passion for writing, offer to work on a writing project for another department – perhaps a piece of marketing writing, a proposal, a requirements document.

Or start a personal blog. The blog could be about technical writing, a hobby, or something you’re passionate about. Blogging makes you consider your audience and work on your writing craft.

Or write an article for your local paper, a short story, a piece of fiction, or morning pages.

Your turn! What do you do to keep your technical writing fresh?


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

Photo via Flickr user Charles Haynes