Date: Sun, 6 Oct 2002 20:29:10 -0700 From: Adam Weinberger <adam@vectors.cx> To: Giorgos Keramidas <keramida@FreeBSD.ORG> Cc: doc@FreeBSD.ORG Subject: Re: 4.7-RC error Message-ID: <20021007032910.GI44643@vectors.cx> In-Reply-To: <20021007052616.W4202-100000@hades> References: <20021007004011.GC44643@vectors.cx> <20021007052616.W4202-100000@hades>
next in thread | previous in thread | raw e-mail | index | archive | help
>> (10.06.2002 @ 1932 PST): Giorgos Keramidas said, in 1.3K: <<
> The correct path is the documented path, and cutting-edge chapter of
> the Handbook clearly references src/UPDATING and not src/README.
i'm not disagreeing that the handbook and reality should be in sync. my
argument is only that the important stuff about how to compile world and
kernel should be moved out of where it is, and into a more accessable
place.
> > makes more sense to me to move src/README to src/REAME.build, and move
> > src/UPDATING to src/README. or, move src/README to src/README.build and
> > create a new README file. one that gives very terse instructions for
> > building world and kernel, and possibly updating the sources. i'd be
> > happy to provide such a file if it sounds like a good idea.
>
> I am not against renaming src/README, but I don't really think there
> are good reasons to do so. The correct file to read for build
> instructions is already documented in the Handbook.
somebody who is feeling around, trying to solve a problem, may (if
they're smart) look for informational files in the current (build) dir.
i know that when i'm frustrated, the first thing i do is 'ls,' just to
keep my brain going. they'll see README and UPDATING. README does not
answer the question "how do i turn this on?" and UPDATING, if you're
unfamiliar with what the file is, looks at a glance to be a reference
for developers or people attuned to the finer points of the build
process.
for example, at this point in time a new user would look in UPDATING,
see a message about using INSTALL="install -C" in Makefiles. one must
scroll down many screens to get to the "COMMON ITEMS" section.
i think it'd be more helpful to a greater base of people to have README
be something different. heck, even a files called src/HOWTO would be
appropriate. just a direct copy of the "COMMON ITEMS" section from
src/UPDATING would be helpful to people.
> Not having read the documentation is not a good reason for renaming
> files around, IMHO. Especially since I don't think that the same
> people who fail to read the existing documentation will also fail to
> read the same file if it's called README.first.
making a src/HOWTO would help reduce the frequency of a few of the most
commonly asked questions on -questions.
-Adam
--
"Oh good, my dog found the chainsaw."
-Lilo, "Lilo & Stitch"
Adam Weinberger
adam@vectors.cx
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?20021007032910.GI44643>