Preparing the Technical Writer

When I first learned to program, I created programs by walking up to a computer, turning it on, and writing some code. What I didn't do is design. I had no idea how to design. How do you turn a blank sheet of paper into software? I didn't feel comfortable thinking about code without a keyboard under my fingers. This is not just a problem with programmers, because some technical writers use basically the same approach. They work with no design, no outline, and, remarkably, no real understanding of the program. They learn how to use the program as they write the documentation.

Does this make sense? Remember that the ultimate goal is to make the Help system helpful. How helpful can documentation be when written by someone, no matter how talented, who doesn't understand the program? The tech writer must become an experienced user before writing in detail. The goal isn't to write documentation for experienced users. Rather, the tech writer needs to understand how to use the program better than the typical user reading the documentation.

What is the best way to achieve this objective? I like to use the following process:

1. Give a demo.

2. Give an outline.

3. Get an outline.

4. Get a demo.

When you first meet with the technical writer, you should start off with a demonstration of the program. Be sure to point out the features that are likely to give users problems. Then present the model Help system you selected and discuss why you think it is an appropriate model. Then present the outline of your preliminary design and get the tech writer's feedback.

At this point, you will give the technical writer a copy of the program and plenty of time to become familiar with it. However, before the tech writer starts writing, I suggest that you have another meeting. You should ask for an outline of what the tech writer wants to write. Review the outline for accuracy and completeness. I also suggest that you ask the tech writer to give you a demonstration of the program and to discuss the specific details of the Help system design while giving the demo. Ask the tech writer difficult questions about the program and how the Help system is going to handle such questions. If the person is struggling to use the program or you don't agree with the proposed approach, you'll know immediately and can take the appropriate action.



Developing User Interfaces for Microsoft Windows
Developing User Interfaces for Microsoft Windows
ISBN: 0735605866
EAN: 2147483647
Year: 2005
Pages: 334

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net