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.
i haven't properly introduced myself yet, so quickly:
my name is kate, i work for a small software company
in san jose, and i'm fairly new to tech writing.
my education has been (and continues to be) in
languages and linguistics, and i envision myself
someday returning to academia, tech writing experience
and all, wiser and grayer for it.
that having been said, please allow me to pick your
Helen Obaze spake thusly:
>- If a chapter has minor revisions (less than half of the chapter has
>changed), I just reprint the revised pages. <snip>
i really like this idea, and would love to apply it to
my bugaboo project, which is the installation manual
for our software. unfortunately, the idea has not gone
over well with those who know our customers the best.
the deal is this: our software has a really icky (yes,
a technical term) installation process, and we have a
team of implementation specialists who visit each site
to make sure the databases are all set up properly, etc.
they all rely heavily on the information in the
installation manual, and what's more, they frequently
want to add new information or simply document it all
better. now we get to the issue of constant revisions.
the implementations team needs frequent updates to this
material, sometimes for very minor changes. (and no one
here seems to like the idea of binders and loose paper.)
the problem is, we've been accustomed to supplying our
customers with this same installation manual, except
for them, it's more of a user reference. definitely
not weekend reading for the technophobe, and not likely
to be useful in its entirety to anyone but us. it boils
down to my having to write for two very different
audiences at the same time.
so it seems logical to make two manuals -- a reference
guide for the adventurous user which is released with
each version of the software along with the other user
documentation, and an implementation manual for internal
use which is updated on a far more frequent basis, and
which would not require the same amount of sparkle and
marketing a user doc gets. what's the problem? well, it
means increasing my already-unrealistic workload, for
one thing. but i'm not one of the opponents. it's also
meeting with opposition from the old-timers (which means,
mind you, a mere three years at this company) who see
this as the beginning of an information gap between tech
support and users, which, they feel, will wind up adding
to the tech support load, not to mention alienating our
i think i'm probably not articulating their opposition
very well, but i'm hoping people on this list have had
to deal with something relatively similar and can share
some wisdom earned from their experiences. but i would
just like to hear some thoughts or suggestions from all.