[gentoo-dev] Documentation linkage or location

[Sven Vermeulen <swift@gentoo.org>]

[-- Attachment #1: Type: text/plain, Size: 2100 bytes --]

Hi,

Currently several Gentoo-related documentation isn't located inside the
documentation part of the cvs ([gentoo]/xml/htdocs/doc). For instance, we
have some nice texts on clustering (in proj/en/cluster), or hardening Gentoo
(proj/en/hardened). Even information on metadata.xml etc. are available, but
in proj/en/metastructure.

Several users and developers don't know this, and this is partly because
those documents aren't linked in the documentation index page. Now there are
two possibilities to resolve this issue:

(1) Link all documentation on the documentation index, but keep the
documentation where it is. This however has one big disadvantage, which is
that only a very very very small part of the documentation team can do
editing on those documents (one person most of the time). The result is that
installation-related documents are quickly outdated (our installation guide
changes a lot, and with the upcoming handbook this won't change :) because
the documentation team can't update the related documents.

(2) Move all documentation in the documentation repository and link those on
the index page. This however has one big disadvantage, which is that only a
small part of the respective project (clusters, hardened, metastructure) have
access to the documentation for updates.

In the eyes of the documentation development, this latter is preferred: at
least one person of each project has (or should have) access to the
documentation cvs (see the "Project Doc Editor" at
http://www.gentoo.org/proj/en/gdp). Further more, updates to documentation
shouldn't be a one-man change -- a second "opinion" must be established (we
just call it reviewing) so that no major mistakes are made (we are all
human).


Are there objections if I would suggest to implement the second proposal
(i.e. migrate documentation to the documentation directory)?

Wkr,
	Sven Vermeulen

-- 
 ^__^   And Larry saw that it was Good.
 (oo)                                      Sven Vermeulen
 (__)   http://www.gentoo.org              Gentoo Documentation Project

[-- Attachment #2: Type: application/pgp-signature, Size: 189 bytes --]