how about:
FreeBSD-Handbook-General (guaranteed to work with all FreeBSD systems,
doesn't include stuff in FreeBSD-Handbook-BRANCH.x)
FreeBSD-Handbook-4.x (guaranteed to work with 4.x branch, doesn't include
stuff in FreeBSD-Handbook-General)
FreeBSD-Handbook-5.x (guaranteed to work with 5.x branch, doesn't include
stuff in FreeBSD-Handbook-General)
FreeBSD-Handbook-6.x (guaranteed to work with 6.x branch, doesn't include
stuff in FreeBSD-Handbook-General)
...
this way layered information is minimalized and there is clear path to
find something out.
FreeBSD-Handbook-General is rather fixed once ready, only maintenance
needed is when some future release doesnt support something anymore, that
is removed and moved to FreeBSD-Handbook-BRANCH.x.
FreeBSD-Handbook-BRANCH.x deals with branch in case from installation to
use, having links to FreeBSD-Handbook-General when needed.
FreeBSD-Handbook-BRANCH.x can also have real-life examples and comments,
so need for FAQ should be covered.
dunno if that is any more clear but what there is out there now, is a
mess.
---J
On Tue, 20 Dec 2005, Ceri Davies wrote:
On Mon, Dec 19, 2005 at 10:34:23AM +0100, Dirk GOUDERS wrote:
3. Full review and update of the install docs, handbook, FAQ, etc.
There are sections that are embarrassingly out of date (one section of
the handbook apparently states that we only support a single brand of
wifi cards). A co-worker of mine tried to install 6.0 using just the
handbook install guide, and discovered that it really doesn't match
reality anymore, in both big and small ways. Contact me directly if
you would like his list of comments.
I am wondering if it wouldn't be advantageous to have "versioned"
documents that just cover one specific release and not to cover all
realeases in single documents.
I could imagine that it is harder to cover everything in single
documents than to perhaps copy the existing documentation when a new
branch is created and edit it to match just the new release.
Maybe, I do not realize how much more work this would be but it would
probably enforce regular reviews of the documentation and the readers
would benefit from it.
This is exactly the idea that I have been pimping to anyone who will
listen for the last three months or so. I also think that it is
advantageous for users who are using, say 4.2, to be able to find
documentation for 4.2 without having to interpret a nest of "if you have
4.x do this, if 5.0 through 5.3 do that, else do the other". I don't
think it's a lot of work to just branch the handbook (and FAQ
if we decide to keep it) - in fact, for me, it would be a definite win -
at release time, but it just doesn't seem to be what other people want
done.
I would encourage those interested to ask about it on [EMAIL PROTECTED]
Ceri
--
Only two things are infinite, the universe and human stupidity, and I'm
not sure about the former. -- Einstein (attrib.)
_______________________________________________
freebsd-hackers@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-hackers
To unsubscribe, send any mail to "[EMAIL PROTECTED]"
