TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
Carl Stiere, writing from the Silicon Tundra just down the
road a spell, wondered:
<<A colleague of mine is documenting an particular sort of
GUI - it's an integrated development environment (IDE) for a
programming language. It's crucial that she help the user
learn to operate this thing in a way that will make life easier --
not more difficult.>>
Based on that introduction alone, I think you have the answer
to all your questions below: document it in such a way that
(to borrow a phrase) makes life easier for the user, not more
difficult. You can safely ignore any advice to the contrary.
<<1) She's got to explain to the user the model of the IDE,
including all the necessary concepts, procedures, inputs and
outputs.>>
No problem... if you're willing to do a quick, painless
audience analysis. We're not talking rocket science here: Sit
down with your developers and single out (say) two or three
who use IDEs somewhat differently. Figure out how and why
they work in that manner (i.e., whether there really are two or
more ways to use an IDE), and come up with a
documentation strategy that addresses the needs of each type
of developer. If you want to be really sophisticated about this,
but still not fall into rocket science, do a Web search for
mailing lists that focus on the needs of developers, and post a
questionnaire on those lists. If you introduce it as an honest
attempt to see how they work so you can help them work
better, you'll probably be deluged with information.
<<2) She may want to present them in a sort of mini-
tutorial.>>
One per developer type, please, since not everyone will work
in the same manner. See previous notes.
<<3) She is limited to Windows online help as the required
medium for this documentation.>>
Assuming you're talking about a Windows IDE, I don't see
any problems. But the IDEs I've seen tend to be somewhat
cluttered, so you've got a tricky information design exercise
ahead of you trying to display the help without concealing the
entire IDE under the help window. Depending on how
scriptable the IDE is and how good you are with wizards etc.,
you may have to give up and resort to paper for the tutorials.
<<4) Someone on the project said, "Nah, don't document the
menus and options!" (that might encourage the user to
experiment with no preparation: the use of the menus and
options should be explained only in context of a model or in
specific procedures).>>
I think this advice is sufficiently and self-evidently worthless
that it doesn't bear further discussion. Provide reference
information for each and every menu choice. Developers love
playing, but they also like to have reference material handy to
help them play more effectively.
