Date: Mon, 8 Jan 1996 09:07:36 -0700 From: kelly@fsl.noaa.gov (Sean Kelly) To: jkh@time.cdrom.com Cc: doc@freebsd.org Subject: Re: How do folks feel about legitimizing the `style split' in our docs? Message-ID: <9601081607.AA10265@emu.fsl.noaa.gov> In-Reply-To: <21683.821075998@time.cdrom.com> (jkh@time.cdrom.com)
next in thread | previous in thread | raw e-mail | index | archive | help
>>>>> "Jordan" == Jordan K Hubbard <jkh@time.cdrom.com> writes:
Jordan> "What the hell is he talking about?" they ask.
Uh oh ... another Jordan diatribe. At least it'll be an amusing read :-)
(Really, I'm kidding!)
Jordan> I'm talking about our long-standing problem with having
Jordan> docs submitted in one of two fairly different styles:
Jordan> 1 "How to do this ..."
Jordan> 2 "How this work works ..."
Yes, I'll agree with this, to a point. There are some aspects of
using and administrating an operating system where education about how
it works is a lot more useful than step-by-step instructions on how to
do something. Teaching someone how to set up an /etc/exports file
goes quite smoothly with: ``1. Using your favorite text editor, ...''
Debugging why the fifth mountd request gets refused after hanging for
ten minutes but only if there are two simultaneous X servers is
definitely not served by ``1. Ummm, let's see, where could we begin?''
Jordan> Instead, we've smashed beginner's guides and expert docs
Jordan> together, resulting in The Handbook. If you try to read
Jordan> it from start to finish, you'll be presented with a
Jordan> bewildering array of stylistic twists and turns as you
Jordan> leave one author's section and move into another's.
True. This is part of the reason why Don Knuth's _TeXbook_ fails.
Despite the so-called dangerous bends, the beginner cannot determine
how to make a report document with tables without skipping around a
lot. The expert cannot determine why a marginal note is adding
vertical glue to the main vertical list without skipping around a lot.
Jordan> I would argue that this is not necessary, nor do we need
Jordan> to split the handbook in half. What I would argue for
Jordan> instead is a further level of subcategorization for every
Jordan> major topic, looking something like this:
Jordan> Subject Heading:
Jordan> <intro text>
Jordan> <howto guide>
Jordan> <how it works>
I like it. But the printed manual really should keep this material
separate, lest we make the same TeXbook mistake. We should be able to
identify SGML-wise which topics should end up in which book.
Jordan> Comments? John, would something like this conflict
Jordan> significantly with your proposed reorg?
I must've missed the proposed reorg ... what's that all about?
--
Sean Kelly
NOAA Forecast Systems Laboratory, Boulder Colorado USA
My girlfriend asked me how long I was going to be gone on this tour.
I said, "the whole time." -- Steven Wright
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?9601081607.AA10265>