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>