On Wed, 4 Dec 1996 09:31:58 -0600 (CST), Kent Landfield
<kent@landfield.com> wrote:
> # Well, we've got about 45K of clues total. This is a lot more than I, among
> # others, think is reasonable. Some suggestions have been:
> What do you mean by "a lot more than is reasonable" ? The key to writing
> a useful FAQ is to focus on the content. I really don't see size being the
> problem that it was 3 years ago. If you are trying to answer questions and
> educate your readership, do so. Don't get in a position of deciding not to
> add something useful simply because it puts you a few K over some archaic
> limit.
> If the 45K of clues is well organized it is not problem at all. I would
So I think what is really being asked is, "How do I organize this
amount of data so as to make it well organized and easily manageable
as well as easily understood". Correct?
Cathy posted some good ideas; in addition, I'd like to suggest
reading some general writers' handbooks. (Unfortunately, most of the
ones I've read were in Swedish and so probably not of much value to
you :-)
Something like "how to write for your local newspaper" might make
more sense than you think, if you can find such a book.
Some ideas, off the top of my head (i.e. badly structured :^)
Try to organize the tips into hierarchical classes several levels
deep. If the division doesn't feel natural, redo it.
At this stage, it's fairly important to try to foresee further
additions as well. A category which is "closed" (succinct enough to
cover exactly what you have now, but nothing more) is probably not
going to serve well in the long run if you expect to need to amend the
FAQ later, although in principle it's important to avoid unnecessary
abstraction.
For each section (aka class, aka topic), it might be helpful to
include a "run-in" which explains the section in broad terms and tells
the reader what the rest of the section is all about. That way, you
can skip topics that are not interesting to you.
Be very generous with subheads. Try to break up long paragraphs into
shorter ones. Ditto for long sentences; they can often be made more
readable by splitting them and slimming them a bit. If something
doesn't fit into the more readable version, consider moving it
somewhere else entirely -- to a whole different topic, or a whole new
category, perhaps.
From a technical point of view, you might want to investigate in tools
that will let you keep different sections in different files although
you perhaps intend to make the end result into one big monolithic
file.
Something along the lines of "structured word processing" a la TeX
can be a wonderful tool for organizing things logically, by virtue of
forcing you to use strict rules. (I can't stand TeX myself but I think
I learned a thing or two from the book.)
By extension, if your employer etc. has a set of rules for internal
documentation, you might want to try to adhere to them, too. They
don't exist just because they like to force things down people's
throats, you know :-)
A picture is worth a thousand words, but it might take you less time
to write those words. Good pictures are not easy to make, especially
not if you're confined to ASCII art.
Don't know how much help this can be -- I don't feel too structured
right now ...
/* era */
-- See <http://www.ling.helsinki.fi/~reriksso/> for mantra, disclaimer, etc. * If you enjoy getting spam, I'd appreciate it if you'd register yourself at the following URL: <http://www.ling.helsinki.fi/~reriksso/spam.html>
[
Usenet Hypertext FAQ Archive |
Search Mail Archive |
Authors |
Usenet
]
[
1993 |
1994 |
1995 |
1996 |
1997
]
© Copyright The Landfield Group, 1997
All rights reserved