Re: Documenting software

[Barbara Roll <broll -at- MICROSOFT -dot- COM>]

Kathy Stanzler asks:

"For those of you who document software applications, how much of what
you do is documenting the GUI and how much of it is documenting the
underlying structure, the means by which the GUI is implemented? In
other words, how important is it, do you think, for tech writers to
understand the inner workings of the software?"

If you document programming applications or your audience is MIS
professionals, then you need to understand how the software works, and you
will probably document both the GUI and the underlying structure.

If your audience is NOT writing applications with or modifying the software,
I would focus on the tasks the user wants to accomplish. Most of the
research I've seen says that users refer to documentation primarily when
they have a problem. So figure out what they want to do (a user task list),
make it your outline, and use it as the basis for your documentation. Keep
in mind that what the user wants to do may involve MORE than what they can
do in your application. For example, a user of project scheduling software
may need to type a list of tasks, and then have team members estimate how
long each task will take before proceeding with the schedule. Depending on
the scope of your documentation, you may want to include guidance for
estimating how long the task takes, even though it isn't actually done in
your product. Think about the context in which the user is using your
product and consider enhancing the documentation accordingly.

Barb Roll