Date: Mon, 2 Nov 1998 05:21:37 +1100 From: Sue Blake <sue@welearn.com.au> To: "Jordan K. Hubbard" <jkh@time.cdrom.com>, Sean Kelly <kelly@plutotech.com> Cc: Nik Clayton <nik@nothing-going-on.demon.co.uk>, doc@FreeBSD.ORG Subject: Re: RFC: Handbook reorganisation Message-ID: <19981102052137.50161@welearn.com.au> In-Reply-To: <18181.909783311@time.cdrom.com>; from Jordan K. Hubbard on Fri, Oct 30, 1998 at 01:35:11PM -0800 References: <363A1E89.DFEC36A0@plutotech.com> <18181.909783311@time.cdrom.com>
next in thread | previous in thread | raw e-mail | index | archive | help
On Fri, Oct 30, 1998 at 01:35:11PM -0800, Jordan K. Hubbard wrote:
> > Commenting on the new organization would be easier if we were to make a
> > statement about what the intended goal and audience is: should the
> > handbook be targeted to the lowest, most computer-unaware user possible,
> > or is some familiarity with Unix assumed (for example)? This should be
>
> I think the only real answer to this question is: Yes. :-)
>
> The usual compromise approach is to make each chapter or section
> follow the same basic flow pattern: You start with simple, 3-4 letter
> words for the beginning and focus on "how to" style information and
> then gradually get more technical until you're covering hacker-level
> information at the end, capped by a further reading section that
> really goes off into the deep end if one exists.
That sounds great if the levels are clearly marked. Some chapters or
sections will be mostly easy stuff and some will move to more
advanced stuff very early. The start and stop signs need to be obvious.
The first few times I read the Handbook, I read it from cover to cover
without any idea that some was unnecessary. The "easy" bits were as
incomprehensible to me as the advanced stuff so it seemed like it all
had to be conquered before installing.
> That way the novice users can just read as far as they need to and
> stop (which their limited attention spam more or less guarantees
> anyway ;)
Ahem :-) their attention span is the same, i.e., they can take in
exactly the same amount of new information as anyone else. It is
difficult for doc writers to realise how many unfamiliar concepts can be
crammed into a single sentence which sounds like a single point to them.
Some novices study on anyway, and get so fed up with the effort (not
knowing they can stop) that they never actually install the damn thing.
> whereas the pros can skim the beginning and only start reading
> seriously at the point where the information density seems high
> enough.
Yes, make them wade through too much boring stuff and they won't bother
reading what we wish they would read either :-)
I like Nik's new outline. It fits my perspective a lot better than the
old. It will still need clear travel guides for different kinds of
users, whoever we decide they are.
Here's some brainstorming in case any is helpful... nothing concrete,
sorry, just a perspective for now.
I'd like to be able to pick up the handbook and instantly find what
an inexperienced new user needs without much searching, and get that
only to the level required for now (with links to more info of course)
and in a sequence that resembles the order in which it can be used.
The stuff that leads to "Look Ma, I'm _using_ FreeBSD" is critical.
Things like:
1 How to get FreeBSD (options, pros and cons)
2 Very basic installation instructions, but including puzzles like
- how to name and number the machine
- lots on how to do an FTP installation (easier to do than it seems)
- whether/how to install what packages at that time*
- how to recognise when the installation has finished and if it worked
- links all along to more installation info in case of trouble
3 Getting around from the shell prompt (WTF is a shell?); shutdown
4 Using ee for now, and mention better options for later
5 Anything that must be done or checked right after installing (using 3&4)
6 Installing the GUI window thing (oh, it's called X? it's not freebsd?)
7 Using X (how to get out, resolution, how the mouse works for copying, etc)
8 Connecting to my ISP (bugger the jargon, that's what I want to do)
9 Installing more packages (use packages or ports? why? how?)
10 Misc orientation stuff:
- Things happen by themselves, like find at 2am, atrun; it's OK.
- Locate doesn't work until Saturday; what do those root messages mean?
- Getting more ttys and mounting (extended) DOS partitions
They're all first day need to know topics for, e.g., Microsoft refugees
working alone from home on their first FreeBSD system, and most of it's
already in there somewhere. It can be too hard to find these topics from
the contents unless you know what their section would be classified
under. For example, I wouldn't have expected to find the windowing GUI
thing under "Applications". Better organisation will help a lot but an
additional read-these-first list might still be necessary.
As you point out, it's important to tell people not only where to start,
but also where to stop. One way of doing this is to use a very brief
overview of a topic in point form, marking the essential newbie
information for first time reading. Another is to present a guide to
first use of the handbook, and yet another is to mark the actual pages.
(Do people still hand out those bibles with lots of passages underlined
for lazy converts with short attention spans? That's the approach.) If
you don't tell newbies what to read, you take pot luck; if you don't
tell them what *not* to read, they'll try to read it all then give up
completely. We never hear from these people, but others do.
It's starting to sound like I'm looking for a separate clueless newbies
document, but no, I'd see that as counterproductive. It should all be
mentioned in the one spot, with pointers to lots of tutorials for even
more in depth easy treatment, but without assuming the reader has enough
experience to choose what to read when. Most people are really new at
some of this and want more advanced info on some other aspects, so it's
convenient to have it all together; everyone starts with the handbook.
And the handbook must be readily available in a recognisably
Microsoft-friendly format if they are to read it before installing, and
it would be nice if there was some easy way to identify and print just
the first-needed sections from Microsoft, because that's what people
will be trying to do with it. (Think about it: col -b is absurd)
You can keep the stuff about allowing people to dial in, networking,
firewalls, quotas, window manager choices and config, and other hacker
stuff for later reading, but please do include everyone's skills under
the "contributing to FreeBSD" heading, however humble they seem.
Good habits start early.
It might be useful to take a similar look from several other
perspectives, and see how many of them can be accommodated in the one
document because of the improved structure. The picture I've painted
here must look awful to people who basically know what they're doing.
Yes, I will be prepared to put my pen where my mouth is if there are
holes to fill. For now I'm just throwing ideas around for criticism.
* In a few weeks I'll be trying to get around this by bundling a small
starter set of packages together that will suit those without a clue,
together with some config files and doccos similarly aimed. I'm still
trying to get a clue myself though :-)
--
Regards,
-*Sue*-
To Unsubscribe: send mail to majordomo@FreeBSD.org
with "unsubscribe freebsd-doc" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?19981102052137.50161>