docs/87445: comments for improvement of handbook/kernelconfig-config.html

[Giorgos Keramidas]

On 2005-10-15 13:20, Ceri Davies <ceri at submonkey.net> wrote:
> [ Moved to doc@ from some other place ]
>
> On Sat, Oct 15, 2005 at 05:58:37AM -0400, Tom Rhodes wrote:
>
> >                                                     Or perhaps
> > 4.X will be knifed from the handbook.  And most likely, the
> > only people who will expect it coming will be those that aren't
> > going to stand in my way.[1]  :)
> >
> > [1]: Please don't take that as if it's rude, I'm actually
> >      joking around with it.  Cause I know that if someone
> >      tried that, well, to core && doceng they'd be explaining.
>
> Actually that's a great idea.  There's no reason why we couldn't, like
> today, commit a copy of the current handbook to handbook4 and then get
> rid of all the crud from the real handbook.  Same deal with the FAQ.
> The information is still available then, but we no longer have to tear
> our own hair own trying to maintain the documents.

The main problem with doing this is that it looks a lot like branching
the docs, and I think this is something that not many people would like.

For instance, what happens with corrections to the 4.X Handbook that
people haven't noticed yet?  Or what happens when we restructure parts
of the HEAD of the Handbook, but fail to do so in Handbooks of earlier
FreeBSD versions?  Are we supposed to 'MFC' Handbook fixes about
grammar, style, or even bugs in the existing examples to Handbook4?

I have given a lot of thought to the fact that we are currently
sprinkling <note> elements around in a more or less "yeah, put them
anywhere you like" manner.  This looks & feels a bit wrong.

I'm not sure if we can support a fully branched doc/ tree though.  It
would be nice to have a section of our website that is very similar to
what one sees on docs.sun.com:

	- FreeBSD 4.X documentation set
		- Articles
		- Books
			- Handbook
	- FreeBSD 5.X documentation set
		- Articles
		- Books
			- Handbook


etc. but that is something I've long postponed suggesting for fear of
some huge, monstrous bikeshed.

If we are to keep separate versions of the Handbook though, why not go
all the way and organize the entire doc/ tree around FreeBSD releases?

- Giorgos