Tech-writers – a necessary evil

Written by Glenn Murray

Continued from page 1

The other risk is that you’ll lose your sense of urgency. And that’s a big part of what makes a good worker. You should be very strict about managing your commitments. This requires discipline, because sometimes it seems you’rerepparttar only one that cares, but you have to do it.

One thing you should be aware of though, is that your average tech-writer in software spends only about 50% of his or her time writing. The rest of your time is spent planning, problem solving, fixing your computer, researching, interviewingrepparttar 133509 programmers, writing work pracs…

I always found it was a good balance, though.

It was when I started managing teams thatrepparttar 133510 bottom really fell out. Thenrepparttar 133511 percentage dropped to about 10-20%. There were times when I’d go months without writing any help at all. That can be very frustrating, especially if you don’t particularly like managing.

Now managing tech-writers in software is an interesting thing. As with most technology management positions, you kinda fall into it, because you’rerepparttar 133512 most senior/experienced person inrepparttar 133513 company. Unfortunately, that doesn’t qualify you to be a manager. Software companies are renowned for dumping people into management roles without any real training or support.

I don’t really have any advice for you here. If it’s gonna happen, it’ll happen. Just be aware of it, and know that if you fall into a management role, it’s gonna be difficult. (That’s not to say that it can’t be rewarding though…)

The ironic thing is thatrepparttar 133514 most difficult aspect of it is that your staff are screaming at you to changerepparttar 133515 system. “The programmers don’t answer our questions!” “None of my work has been reviewed forrepparttar 133516 last 2 months!” “The project manager just told me to forget about quality!”

Unfortunately,repparttar 133517 inexperienced tech-writer is often naïve enough to think they can changerepparttar 133518 system. Once you become a manager, you know you can’t. Hold on a minute… Maybe apathy is what qualifies you to be a manager… Hmmmm.

In any case, my advice is not to push too hard. You’ll make life hard for your manager, and give yourself a bad reputation. Recognise you’re a necessary evil, and work within those constraints.

Tech-writing can be a lot of fun. And don’t let anyone tell you it’s not creative. Trying to think of a way to describe what goes inrepparttar 133519 Name field without just saying “Enterrepparttar 133520 name” is a real mind-boggler!

* Glenn Murray is an advertising copywriter and heads copywriting studio Divine Write. He can be contacted on Sydney +612 4334 6222 or at Visit for further details or more FREE articles.

Writing Helpful Help – A Minimalism Checklist

Written by Glenn Murray

Continued from page 1

7. Fix mistakes - "Re-enterrepparttar path"

8. Provide error info at end of tasks where necessary (rule of thumb, one error info note per three tasks is a good average)

9. Don't break up instructions with notes, cautions, warnings, and exceptional cases - Put these things atrepparttar 133508 end ofrepparttar 133509 instruction, wherever possible

10. Be brief, don't spell everything out, especially things that can be taken for granted

11. Omit conceptual and note information where possible, or link to it. Perhaps provide expansion information atrepparttar 133510 end ofrepparttar 133511 topic, plus maybe a note that there are other ways to performrepparttar 133512 task/goal, but this isrepparttar 133513 easiest

12. Sections should look short and read short

13. Provide closure for sections (e.g., back to original screen/goal)

14. Provide an immediate opportunity to act and encourage exploration and innovation (use active invitations to act, such as, "See for yourself..." or "Try this..." rather than passive invitations such as, "You can...")

15. Get users started quickly

16. Allow for reading in any order - make each section modular, especially goals, but perhaps tasks (definitely if they can be performed in different order)

17. Highlight things that are not typical

18. Use active voice rather than passive voice

19. Try to account forrepparttar 133514 user's environment in your writing

20. Before writing anything, ask yourself “Will this help my reader?”

By building these practices into your documentation process, you’ll find that your online help becomes easier to write, shorter, and far more usable for your reader. What’s more, your boss will love you!

* Glenn Murray is an advertising copywriter and heads copywriting studio Divine Write. He can be contacted on Sydney +612 4334 6222 or at Visit for further details or more FREE articles.

    <Back to Page 1 © 2005
Terms of Use