Skip site navigation (1)Skip section navigation (2)
Date:      Thu, 28 Dec 2006 04:54:38 -0800 (PST)
From:      eps+pqry0612@ana.com (Eric P. Scott)
To:        "Simon L. Nielsen" <simon@FreeBSD.org>
Cc:        freebsd-stable@FreeBSD.org
Subject:   Re: FreeBSD 6.2-RC2 Available
Message-ID:  <200612281254.kBSCscUU027061@anna.ana.com>

next in thread | raw e-mail | index | archive | help
>http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/install-diff-media.html#AEN3220

Let me try to explain what's wrong here...

This URL corresponds to "Preparing Your Own Installation Media,"
which appears after "Advanced Installation Guide."  That's sure
not the first place I'd look.  Titles like "Choosing What to 
Install" or "Choosing Your Installation Media" are what are going
to catch my eye.

In a reasonably organized document, "Troubleshooting" would
typically follow the last section with any content of interest to
most readers--and I wouldn't look there unless I already had
everything I thought I'd needed, actually attempted an
installation, and then it failed somehow.  Everything following
this section should be applicable to even fewer situations.

I'd expect "Advanced Installation Guide" to cover truly unusual
("special purpose" as opposed to "common installation")
situations, and "Preparing Your Own Installation Media" to
pertain to "remastering" (to borrow a term from Those Other
Guys)--something I would never, ever be interested in doing
(at least not any time in the foreseeable future).

Basically, the titles are deceptive, and the Handbook is
structured in such a way that it doesn't present information in
any sort of logical order.

That aside, the Handbook is hardly the first place anyone is
going to start.  I'd probably begin with the Hardware Notes for
the -RELEASE to determine whether I should be bothering trying to
install FreeBSD at all.  Then I'd look at the Release Notes to
see if there are any "gotchas" I should be aware of.  After that,
the Installation Instructions for my architecture.  That's where
I'd expect these questions to be answered.

What's the first "meaningful" section in that document?  How to
install from Floppy Disks.  Heck, most computers sold today don't
even have floppy drives.  That's followed by a section that
mentions CDROM installation, but then starts babbling about boot
floppies again.  The first bullet point refers to "_the_ FreeBSD
installation CD" but if I don't have something in my hot little
hands that clearly says "Hi!  I'm the FreeBSD installation CD
you're looking for," that instruction isn't immediately helpful.

Skipping past a number of sections that are clearly irrelevant, I
come upon, e.g. "Question and Answer Section for i386
Architecture Users."  My question isn't addressed here.  That's
followed by "Distribution Format"--a title that sounds promising.
But it quickly becomes apparent this isn't going to answer my
question, either.  The subsequent sections increasingly smack of
"not applicable," and finally I arrive at the "Troubleshooting"
section, which tells me it's time to stop reading this document.

Oh, there's a README file, which advises potential users to
purchase commercially published media: "This is frequently the
most convenient way to obtain FreeBSD for new installations."

Why is that convenient?  Because the discs are presumably labeled
in a meaningful way, and they're likely accompanied by a piece
of paper, slightly smaller than the front of a jewel box, that
provides a concise "quick start guide."

Having given up on the -RELEASE documentation, my next stop is
going to be to the www.freebsd.org home page.  Look, there's
a FAQ link there.  The FAQ page has a Table of Contents that
begins Introduction, Documentation and Support, Installation.
So, of course, I'm going to head straight to Installation.

The very first item is "Which file do I download to get
FreeBSD?"  Hey, that sounds like my question.  *click*
The answer says I need floppy images?!?  No!  No!  That's not
what I want!

You need to try to put yourself in an end user's frame of
reference.  It's easy to understand why even fairly experienced
folks can find FreeBSD documentation baffling.  I'm sure a fair
number give up in disgust, and fall prey to the next evangelist
who hands them an Ubuntu CD...

P.S. The URL you gave makes no mention of "docs" or "livefs"
images.

					-=EPS=-



Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?200612281254.kBSCscUU027061>