Date: Sun, 07 Jan 1996 20:39:58 -0800 From: "Jordan K. Hubbard" <jkh@time.cdrom.com> To: doc@freebsd.org Subject: How do folks feel about legitimizing the `style split' in our docs? Message-ID: <21683.821075998@time.cdrom.com>
next in thread | raw e-mail | index | archive | help
"What the hell is he talking about?" they ask.
I'm talking about our long-standing problem with having docs submitted
in one of two fairly different styles:
1 "How to do this ..."
2 "How this work works ..."
Contrast the difference between a driver's manual ("when you see a red
light, STOP!") and an owner's manual ("If you open your hood, you'll a
collection of hoses and mysterious chunks of metal - this is how they
work and how to fix them when they stop"). Both can be extremely
valuable during the period where you own and operate your car, but few
would argue that there are many instances when they'd both be used at
the same time, or even necessarily by the same people.
However, despite the fact that much is also true for operating systems
documentation, we've not seen fit to make two books out of it.
Instead, we've smashed beginner's guides and expert docs together,
resulting in The Handbook. If you try to read it from start to
finish, you'll be presented with a bewildering array of stylistic
twists and turns as you leave one author's section and move into
another's.
I would argue that this is not necessary, nor do we need to split the
handbook in half. What I would argue for instead is a further level
of subcategorization for every major topic, looking something like
this:
Subject Heading:
<intro text>
<howto guide>
<how it works>
E.g., you might have something like:
1.2. Network communications with SLIP
Contributed by <authors ..>.
SLIP is a serial point-to-point protocol for allowing remote hosts to
speak TCP/IP to one another over dialup or hardwired links. It use
has been largely superceded by PPP, but there are still situations
where SLIP is useful.
11.2.1. How to set up SLIP
11.2.2. How SLIP works
And the reader would have three `touchpoints' on the page. The intro
if they have no idea what SLIP is ("am I even interested in this?"),
the `How To' choice if they're definitely interested and need to know
how to actually do it step-by-step, and the `How it works' choice if
they're more interested in knowing how it all works (and possibly
because they don't want step-by-step, they just want to know which
parts of the system are "reponsible" for the feature in question).
I have the feeling that if we could sweep large sections of the
handbook into one category or the other, it would both make the whole
thing a lot more readable, and it would point up (through the empty
sub-sections) just where we were deficient in howto or hacker
documentation.
Comments? John, would something like this conflict significantly with
your proposed reorg?
Jordan
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?21683.821075998>