Tech-writers – a necessary evil

Written by Glenn Murray

New to tech-writing, or thinking about starting? The key to success is recognising that tech-writers are a necessary evil.

Tech-writers are necessary because someone has to writerepparttar user doco. The programmers and managers sure as hell don’t want to. This is actually part ofrepparttar 133509 reason that you’re evil, too. In my experience, most programmers and managers think that they could writerepparttar 133510 manuals if they wanted to… they just don’t want to. They might not write all “flowery” likerepparttar 133511 tech-writers, but what they write is correct.

Unfortunately, that’s quite often all that’s important to programmers and managers. There is a feeling withinrepparttar 133512 software environment that accuracy = quality. Audience analysis, doco readability, consistency, usability, active and passive voice, commas in a list of three or more items… All of these things are relatively unimportant to everyone butrepparttar 133513 tech-writer. Oh… andrepparttar 133514 user.

In a world where accuracy is all important, a lot goes overrepparttar 133515 head ofrepparttar 133516 dummy. I don’t know if it’s intellectual snobbery, but programmers and managers seem to think that if they understand it, so shouldrepparttar 133517 user. It doesn’t matter whether or not they do… they SHOULD! Stupid users! Maybe it’srepparttar 133518 geek’s ultimate revenge…

Your document can be 100% accurate, but ifrepparttar 133519 audience can’t read it, you’ve wasted your time.

So why doesn’t anyone acknowledge this? They do! That’srepparttar 133520 weird part. In theory, everyone agrees with you, it’s just in practice that you find yourself out inrepparttar 133521 cold. I don’t know why this happens. Maybe it’s because most of these guys have never done tech-writing.

So tech-writers spend too long worrying about unimportant things. And they bother programmers and managers with unimportant things. But they’re necessary things. Otherwise why would you be employed. Mayberepparttar 133522 absence of simple logic short circuits their brains. Who knows?

What we can get out of this is that there’s a feeling that tech-writers waste time, and as a result, they’re pretty much atrepparttar 133523 bottom ofrepparttar 133524 heap inrepparttar 133525 software world. I think a good analogy isrepparttar 133526 way some rich seerepparttar 133527 poor. Dirty little creatures… if only we could do without them…

But there is an up-side. I don’t want you thinking it’s all bad.

Being atrepparttar 133528 bottom ofrepparttar 133529 heap has its advantages. You can go unnoticed for years if you want. If you haven’t seenrepparttar 133530 movie, Office Space, you should hire it. There’s a little ferrety bloke in that who was “let go” years ago. Problem is, no one ever told him, and because of a glitch in payroll he still got paid. No one ever noticed.

Being a tech-writer’s a bit like that.

When I was managing doco teams, my favourite saying was “All we have to do is manage their expectations and our commitments”. Because programmers and managers resign themselves torepparttar 133531 fact that they don’t know what’s going on inrepparttar 133532 doco team, there’s sometimes a temptation to slacken off. Don’t give in to this temptation!!! If you ever get caught, doing it, it’ll be likerepparttar 133533 boy who cried wolf – they’ll never believe your estimates again!

Writing Helpful Help – A Minimalism Checklist

Written by Glenn Murray

User documentation is all too often written by programmers for programmers. It tends to focus onrepparttar product’s features, rather thanrepparttar 133508 user’s tasks. Generally, programmers aren’t inrepparttar 133509 ideal position to be writing user documentation. They’re too close torepparttar 133510 bits and bytes, and they’re too far fromrepparttar 133511 user. To them, whatrepparttar 133512 product can do tends to be far more important than whatrepparttar 133513 user can do withrepparttar 133514 product.

It’s a subtle – but vital – distinction. Research shows thatrepparttar 133515 key to effective user documentation is writing task oriented help. Even better, write your help according torepparttar 133516 minimalist theory. Inrepparttar 133517 documentation world, “minimalism” is a fancy word for a commonsense practice. In basic terms, it means write to your reader and keep it simple.

The theory itself has a lot of twists and turns. If you want to read a great – but slightly wordy – book onrepparttar 133518 subject, check outrepparttar 133519 book “Minimalism Beyondrepparttar 133520 Nurnberg Funnel”, 1998, edited by John Carroll.

Inrepparttar 133521 meantime, if you can tick every item inrepparttar 133522 following checklist, you’ll be well on your way to usable online help that both your readers and your managers will thank you for.

Helpful Help Checklist

1. Baserepparttar 133523 help on real tasks (or realistic examples)

2. Structurerepparttar 133524 help based on task sequence – Chapter headings should be goals and topics should be tasks

3. Respectrepparttar 133525 reader's activity – this is generally more about what you don’t do than what you do. Don’t wasterepparttar 133526 reader’s time by diving off into tangents

4. Exploit prior knowledge and experience – Drawrepparttar 133527 reader’s attention to previous tasks, experiences, successes, and failures

5. Prevent mistakes - "Ensure you do x before doing y"

6. Detect and identify mistakes - "If this fails, you may have enteredrepparttar 133528 path incorrectly"

Cont'd on page 2 ==> © 2005
Terms of Use