Documentation process, style guide, intranet?

Subject: Documentation process, style guide, intranet?
From: "Hart, Geoff" <Geoff-H -at- MTL -dot- FERIC -dot- CA>
To: "Techwr-L (E-mail)" <TECHWR-L -at- lists -dot- raycomm -dot- com>
Date: Mon, 13 Mar 2000 09:53:32 -0500

Linda Stark is full of questions today <g>:

<<At the moment, our company's intranet has nothing more than some HR forms.
I would like to make it into a dynamic tool that all of our field offices
and our headquarters personnel will find useful in their day-to-day

The first thing to do is get an idea of what kinds of things your target
audience could do most effectively if you made the information available on
the intranet. A quick survey _of all the major staff groups_ should get you
started on identifying the immediate needs, and also sets up a precedent:
that people who have good ideas on how to use the resource are encouraged to
come to you with suggestions. Unlike in Field of Dreams, "if you build it,
they won't come"... but if they build it, you can bet they're going to use
it. Actually figuring out how to organize these things efficiently is a bit
tougher; you'll have to look at ease of access issues and issues of logical

Perhaps the biggest thing of all to keep in mind: make sure you plan and
design the intranet so it'll be easy to maintain and upgrade in the future.
These things grow like kudzu, and the better your initial design, the easier
it'll be to add to it and still keep things under control. And document
everything very well, and choose logical names for the files; the names that
seemed reasonable a year ago might just turn out to be completely
meaningless now if you didn't choose them carefully and write them down in a
book somewhere. I'm currently beating my head against a redesign of our own
intranet. The recently departed (hurrah!) designer chose informative names
such as "icon 37" and "indexbf" for many of the files. Maybe this meant
something to her...

<<While working on my half of the Web site, I also realized that the other
"commercial" side doesn't have a quality control process. Their marketing
info is full of errors in spelling, punctuation, etc.>>

Marketing and technical writing have all the love and sympathy for each
other expressed by cats and dogs vying for the affections of a single owner.
It would be nice if you could bring them back from the dark side of the
Force and get them to use you and your colleagues as a writing resource, but
(i) that can be a very difficult sales job and (ii) you need to ask yourself
whether you can really handle all the extra work. This is certainly worth
the effort, but it might be better to get your own house in order first, and
once that's running smoothly, offer to do the same thing for the marketing

<<As I see it, the first thing we need is a company style guide. ... I need
some guidance (or an idea of where to look for the info) about how to plan a
style manual.>>

This issue has been discussed repeatedly and in some depth on techwr-l and
copyediting-l. Have a look at the archives using the search term "style
guide" and you'll find lots of suggestions. You mentioned that you see
little point in reinventing the wheel, and that's an important point: I've
yet to see a style guide that includes Webster's Unabridged Dictionary as an
appendix, and there's a good reason for that. Your should base your guide on
a style guide that's appropriate for your own industry, and should basically
say "except for the following points, see [style guide name] for details".
John Renish has produced and regularly updates an increasingly comprehensive
bibliography of technical writing resource books; you can find it via the
techwr-l web site, so have a look there. You could also take a look at my
recent article on style guides ("The style guide is dead: long live the
dynamic style guide", Intercom, March 2000, p. 12-17). My article also
includes a few references to useful recent articles on developing style
guides. Once you've got a core style guide that answers most of your
writers' questions, identify the types of things that it doesn't cover
(e.g., acronym lists, specific terminology preferences and prohibitions for
your company, contents of reports, workflow and editing/peer review
instructions, etc.). Let your authors be your guide here, plus pay attention
while you're writing and editing materials: what questions do you need to
answer, what resources provide those answers, and where do you have to make
up your own answers?

<<From there, I can work up a sample plan for the intranet, do some
storyboards, sample pages, etc. Does anyone know where I would find that

I like to recommend the trick that some architects use before they build
pathways between buildings: they simply lay the lawn, then wait for heavy
traffic by people taking shortcuts between buildings to kill the grass in
certain areas. The dead grass nicely marks out the preferred locations for
paved trails. In your case, talking to the various audiences will tell you
how people prefer to "walk" through your information, and that will help
define the structure and layout. You can also use your storyboards for a
simple form of usability test, and let the users test it out and point out
any problems.

--Geoff Hart, FERIC, Pointe-Claire, Quebec
geoff-h -at- mtl -dot- feric -dot- ca

Hofstadter's Law: The time and effort required to complete a project are
always more than you expect, even when you take into account Hofstadter's

Previous by Author: RE. Am I employable?
Next by Author: "Copyleft" doesn't solve _our_ problems.
Previous by Thread: Re: Missing letters in PDF files
Next by Thread: configurable help systems/documentation

What this post helpful? Share it with friends and colleagues:

Sponsored Ads

Sponsored Ads