Date: Mon, 8 Jan 1996 18:07:22 -0500 (EST) From: John Fieber <jfieber@indiana.edu> To: Greg Lehey <grog@lemis.de> Cc: "Jordan K. Hubbard" <jkh@time.cdrom.com>, doc@freebsd.org Subject: Re: How do folks feel about legitimizing the `style split' in our docs? Message-ID: <Pine.BSF.3.91.960108172323.235H-100000@fieber-john.campusview.indiana.edu> In-Reply-To: <199601081747.SAA00295@allegro.lemis.de>
next in thread | previous in thread | raw e-mail | index | archive | help
On Mon, 8 Jan 1996, Greg Lehey wrote:
> Jordan K. Hubbard writes:
> >
> > (sorry, I was too lazy to copy the original message, but...)
>
> This is a thing that I've done a lot of soul-searching about. I agree
> with Jordan's original concerns, so much that I wouldn't be able to
> get a really good assessment in in time to be of use to anybody, so
> I'll give you a rough assessment. Basically, yes, we need both
> approaches. We probably need a larger number than 2.
First, as has been stated, The TeXBook approach is horrible. The TeXbook
would have worked much better if all the `dangerous bends' were moved to
a "part 2".
HOWTO documents that provide a recipe for accomplishing a task typically
do not provide the user with any transferable knowledge. They are also
extremely fragile and can be completely derailed by the slightest
complication. Running FreeBSD is certainly not without complications!
If you try to take into account the most important complications, you end
up with a mess as Greg illustrated with the installation document.
At this point, we ponder: "Gee, if we told them how this thing works,
they might be able to figure out how to get around these complications on
their own!"
Then reality intrudes: "People don't read documentation, and they
certainly don't read documentation that does not appear to address the
problem at hand. In all likelyhood, they might not even identify a
how-it-works document as being relevant to their problem at all."
In this dilemma, we have job security for technical writers.
Although programmers won't hear of it, many documentation problems are
really software design problems. For example, kernel configuration. The
current state of affairs is similar to a person purchasing a car. On the
lot it is configured in such a way that it can be driven off the lot.
Once home, the user must then replace the transmission to effectively use
the car. The analogy falls apart fairly quickly, but you get the idea.
The user suddenly has to know what a transmission is, details about
different sorts of transmission, how they work, and how to remove one and
install another.
Kernel configuration is similar. So, we write a document that explains
the process, things that you can put in a file and such. We also warn
the user of the more common ways they can shoot themself in the foot.
People blunder through and sometimes come out with an operational kernel,
but not after bothering everybody on the hackers and questions list.
This is the Unix Way. In this case, I would argue that the documentation
needs to be built into the process, and the process needs to be
clarified. (Why do we rebuild kernels anyway?) Where redesign does not
eliminate the need for documentation, the documentation should be
supplied on a just-in-time basis. The right document when and where you
need it and invisible the rest of the time.
To my point, I believe that many of the HOWTO sorts of documents are most
effective in this form because they can track what actually happens,
making all the contingency plans as transparent as possible to the user..
As for the how it works documents, at this time, I don't think you can
beat paper!
I'm pessimistic about making anything but incremental improvements on the
documentation front because implementing just-in-time documentation
requires rethinking tool design, and rethinking it in a way that just
might not go over too well with a large population of unix users who have
already invested years of time in learning to use the system.
> instead of pointing to a page ("See Chapter 15, Signals, page 247"
> becomes "See Chapter 15, Signals, the section entitled "BSD signal
> handlers"). The result is that you either have to sequentially search
:(
Blech. Did they give any reason?
> This is the point. I'm not really happy with the way you navigate
> through HTML documents anyway (maybe I just don't understand them),
No, you understand them. It is suboptimal hypertext. Hypertext itself
is a bit of a problem for us humans who can only keep 7 or so things in
our head at a time.
-john
== jfieber@indiana.edu ===========================================
== http://fieber-john.campusview.indiana.edu/~jfieber ============
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?Pine.BSF.3.91.960108172323.235H-100000>