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've just been assigned the task of developing a facility guide for a large
> energy services corporation. My client has almost no existing
> documentation and this is the first time I've created a document of this
> type. Does anyone with this type of experience have some pointers/advice,
> or better yet, examples they would be willing to share?
One of the first intranets we did had an emphasis on facilities. And because
of its ease of access, I heartily recommend this method of access.
In this client's case, there were two kinds of facilities: physical facilities
such as buildings, parking, office furniture, phones, moving from one location
to another,etc.; and network facilties which included where to find
applications, where to store your files, what to do when your group needed more
disk space, etc. Then spanning both kinds was the emergency instructions,
including the disaster plan that categorized 10 different kinds of emergencies,
ranging from power being off to a full-scale building knockdown due to an
earthquake or other major calamity.
The intranet section we devised had extensive indexes and a lot of cross-tree
jumps so that people could find just about anything from just about anywhere.
(I say "intranet section" because, like so many intranets, this one was
developed first and rapidly caused the development of other sections and then a
whole rearrangement, etc. If you've deployed an intranet, you know what I'm
The physical facilities section included short pieces on the various buildings
and what groups were housed where, the various parking lots and parking policy,
security arrangements including after hours and weekends, wiring diagrams and
phone diagrams (accessible only by password), how to order furniture and phones
for new cubicles, how to move from one cube to another, how to update the
master directory, etc. The network facilities section included company
policies on data storage and backup, an explanation of the file system
everybody used, how new applications were acquired, tested, and released to
internal users, how to get a userid and password, how to submit hours and
expenses, and all sorts of things related to a fully networked company.
How do you approach creating such a 'document?' Start by canvassing a
reasonable sampling of users and ask how they'd use it. Ask them for topics
that should be included. By all means ask your boss, and his boss too. Once
you have a good-sized want list, go back to your boss and discuss how to cut it
down to size for the first iteration. You'll probably find far too many topics
for the amount of time your boss wants you to spend on it. Once you have some
agreement on how much to write, just start collecting information, and when you
have a section written, pass it by the source people for verification.
BIG WARNING: a writer is usually never done with this type of project.
Further, depending on its visibility, and particularly if it's part of a
company intranet, it becomes a highly attractive candidate for any group trying
to improve its image. So plan ahead for its expansion and for systematic
updates, as well as the distinct possibility that you'll have to hand it off to