[gentoo-dev] Documentating advanced portage feaetures in Gentoo Handbook

[Sven Vermeulen]

Hi guys,

There's a small discussion going on on gentoo-doc [1] about documenting (or
not documenting) advanced portage features in the Gentoo handbook. The
suggestion currently is to have it as an added chapter in "Working with
Portage" of which you can find a preview on [2] (don't mind the numbering).

[1] http://archives.gentoo.org/gentoo-doc/msg_f3c1439def8cd1df8b0f57fdbb7e6462.xml
[2] http://dev.gentoo.org/~swift/docs/previews/hb-portage-advanced.xml

The discussion however is if it is okay to document these things there or
not. Some of the features are considered to be too "fragile" to be broadly
documented (at least in a beginners resource like the Gentoo Handbook) and
might cause eventual bugs to be closed as RESO:WONTFIX because the user used
such a feature.

Since you're the community at large for supporting stuff, we'd like to know
if it is okay to document these things in the Gentoo Handbook (and if we
need to put in specific warnings to ensure people don't abuse the
functionality) or if you would rather not see it in.

I personally don't think we cannot "not document" it. Eventually, the Gentoo
WiKi will have it documented anyhow, and I already notice that many of the
features are already used in #gentoo or gentoo-user@g.o. But there's still a
difference between "not documenting" and putting it in the Gentoo Handbook.

Thoughts? Suggestions?

Wkr,
	Sven Vermeulen