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.
Subject:Re: The big picture (more than grammar) From:Scott Miller <smiller -at- PORTAL -dot- COM> Date:Fri, 12 Mar 1999 11:09:28 -0800
I keep going back to the rule "give the user the right information at the
right time." The problem is that some delivery mechanisms are better for
some types of information. Windows help, and online documentation in
general, gets harder to use as you add more information, so we tend to leave
out conceptual stuff in favor of procedures. We end up doing a bang-up job
at explaining little individual tasks, like how to create a numbered list,
but don't really give the big picture a lot of airtime.
A solution that has some appeal is to create a small, possibly printed,
"getting started" book that describes the big picture. For example, we're
working on a document that describes each of our GUI tools from the
perspective of how to use the tool in a general sense, more like strategies
for using the tool. So, we tell them things like which tasks are appropriate
for a newly-trained person, and which are for the more supervisor-like
person; what the typical work flow is when using the tool, ways they can use
the tool that aren't readily apparent (for example, using email as a to-do
list), and so forth.
This type of document is useful for new employees, especially when it's
printed since it's common to not have a computer set up on the day you
start. Also, if you leave it out of the online help, it doesn't become
obsolete information that just clogs the pipes.
- Scott M
"Refuses to spell-check most email messages."
> A few years ago, I asked a project/marketing engineer assigned to guide
> my writing efforts why we wouldn't want to include certain illustrations
> and explanations -- concept stuff. Stuff I considered big picture but
> valuable for that reason. He said "We don't need that information in
> there. This is a reference manual we're doing."