Manage Your Tech Writer

Question: We have a contract writer doing online Help for us using Madcap Flare. She has worked at our company for seven weeks. We have only seen a demo, with seven of the Help topics written. Is this normal? How many hours does it take a tech writer to write online Help?

Answer:Let’s say your contract writer works about 36 hours per week (VERY normal for a contract writer). Although often, when they’re really conscientious and up against a deadline, they’ll work 60 hrs./week.

Your contractor has logged in 274 hours up to this point. Normally, a writer would write the directions for one topic in about four hours (some will take a LOT less, some a little more). If your writer has only turned out seven topics, that’s 39.14 hours per topic written up.

Since he works 36 hrs./week, he should have given you directions for nine tasks/topics by the end of each week. You could have demanded that he do so in order to get paid. He’s worked the equivalent of 7.5 weeks, so he should have produced directions for 68 topics by now. This formula holds true for procedures written in a Flare Help system or for a book (it’s the same writing process):

1. Try the action and take notes while you’re doing it (30 minutes).
2. Ask questions when you get stuck (20 minutes).
3. Type the necessary steps (one hour).
4. Test your steps (20 minutes).
5. Fine tune (30 minutes).
6. Release, distribute for review (30 minutes).
7. Incorporate reviewers’ comments (45 minutes).

Incompetent, inexperienced tech writers won’t like my answer to your question. You have to manage them tightly, just like programmers. Follow the Agile methodology for technical writing. It works really well for both tech writing and programming. If you hire a tech writer from Techwriters, our company, we can manage them if you wish.

Question: I have not received any pages of instruction from the tech writer I hired. He’s been on the job for four weeks. Does it take this much time to start writing the customer instructions we hired him to write for our product?

Answer:You have good instincts. Something’s wrong. You must insist—immediately—that this writer give you pages of numbered-step instructions for tasks your customers will need a little help doing with your product.

After four weeks, the wrier should have created a Table of Contents showing the items he will instruct users to accomplish. You have to insist upon receiving a deliverable from a tech writer, and give them a deadline. Very, very often, a technical writer will use up two months and nobody has any pages of instructions to show for all of that money.

Has he done a list of topics, tasks he’ll have to teach them how to do? Each task becomes a different topic in the online Help. It’s hard to write the procedures and self test them. He needs to start writing how to do A, B, C, D, etc., immediately.

Do not accept writing that just walks the user through how the programmers built the software: the different modules, the names of the different screens. That’s useless for the reader who wants to look something up: how to DO something, by a logical name for that task, such as Start a New Account, Close an Account. Programmers NEVER take this activity or task-based approach. That’s where the tech writer comes in.

Once the writer has identified 30 different processes or activities your users will do, it’s reasonable to require a deliverable of ten of those task instructions per week. He has to circulate his drafts of his numbered steps to your developers to review (a technical review), then get their comments and incorporate their comments into his numbered steps.

Require that you see a list of tasks, topics, items for a Help Index (all the same thing) that your writer has researched and come up with before he gets another check. He can’t start producing the Help until he knows what he’s going to write up: tasks, tasks, tasks, jobs, actions, end results that the users want to accomplish.

The writing itself (he should have started it by now) must look like the Help you see when you query something in Word, Excel, or PrPt. Go into Help from any of those programs. Ask the Help how to do something. Print out what you get from Microsoft. That’s what you want your online Help to look like, read like.

WHAT THEY CAN WASTE MONEY/TIME DOING
There’s SO MUCH a writer can research, read, explore, investigate, look into. None of it matters, except writing those pages of instructions: the user guide, the online Help. That takes 100% focus, dedication, experience, and talent. It’s really, really hard and time consuming to write what—and I hope you will look at it from Word or Excel—real, useful Help looks like. You could print it from Word or the other apps and show it to your writer. It reads short, crisp, to the point—nothing extra. That’s REALLY hard and time consuming to do. It takes a first draft, then a lot of polishing. Your writer thinks that he can do this work later, but he does not know how much time it takes. Otherwise, he would have started it by now. He probably figures that he can knock it out later. Wrong. When you do that, it comes out sloppy, full of mistakes.

I can absolutely guarantee you that ‘current documentation’ this writer has spent so much time reading does not meet the “Does this tell me how to do a task?” criteria. That’s why there’s so much of it. It’s a system spec, telling how they constructed the software modules. Your writer must act like a newspaper reporter. He’s going to have to get the real story of what they actually DO using your new software app—not how it was built. Then he has to play with the software himself, do each task himself, recording the path you have to take through this and that screen.

THE AGILE DEVELOPMENT PROCESS
Currently, programmers and technical writers follow the Agile Development Process, as defined by Martin Fowler. Your writer needs to start doing this. The writer (and you) need feedback on the instructions you will release to your customers. The key to getting this feedback is iterative development.

Iterative development has been around for a while under many names: incremental, evolutionary, staged, spiral... lots of names. The key to iterative development is to frequently produce working versions of the final system (or user instructions). They should be as carefully tested as a final delivery. When people actually see the product (instructions), flaws become truly apparent.

The only stable plans are short term plans that are made for a single iteration. Iterative development gives you a firm foundation in each iteration that you can base your later plans around. A key question for this is how long an iteration should take. XP suggests iterations of one or two weeks. The tendency is to make each iteration as short as you can get away with. This provides more frequent feedback, so you know where you are sooner.