Gentoo Archives: gentoo-dev

From: Sven Vermeulen <swift@g.o>
To: gentoo-dev@g.o
Subject: [gentoo-dev] Documentation linkage or location
Date: Thu, 23 Oct 2003 07:30:46
Message-Id: 20031023073039.GA1697@gentoo.org
1 Hi,
2
3 Currently several Gentoo-related documentation isn't located inside the
4 documentation part of the cvs ([gentoo]/xml/htdocs/doc). For instance, we
5 have some nice texts on clustering (in proj/en/cluster), or hardening Gentoo
6 (proj/en/hardened). Even information on metadata.xml etc. are available, but
7 in proj/en/metastructure.
8
9 Several users and developers don't know this, and this is partly because
10 those documents aren't linked in the documentation index page. Now there are
11 two possibilities to resolve this issue:
12
13 (1) Link all documentation on the documentation index, but keep the
14 documentation where it is. This however has one big disadvantage, which is
15 that only a very very very small part of the documentation team can do
16 editing on those documents (one person most of the time). The result is that
17 installation-related documents are quickly outdated (our installation guide
18 changes a lot, and with the upcoming handbook this won't change :) because
19 the documentation team can't update the related documents.
20
21 (2) Move all documentation in the documentation repository and link those on
22 the index page. This however has one big disadvantage, which is that only a
23 small part of the respective project (clusters, hardened, metastructure) have
24 access to the documentation for updates.
25
26 In the eyes of the documentation development, this latter is preferred: at
27 least one person of each project has (or should have) access to the
28 documentation cvs (see the "Project Doc Editor" at
29 http://www.gentoo.org/proj/en/gdp). Further more, updates to documentation
30 shouldn't be a one-man change -- a second "opinion" must be established (we
31 just call it reviewing) so that no major mistakes are made (we are all
32 human).
33
34
35 Are there objections if I would suggest to implement the second proposal
36 (i.e. migrate documentation to the documentation directory)?
37
38 Wkr,
39 Sven Vermeulen
40
41 --
42 ^__^ And Larry saw that it was Good.
43 (oo) Sven Vermeulen
44 (__) http://www.gentoo.org Gentoo Documentation Project

Replies

Subject Author
Re: [gentoo-dev] Documentation linkage or location "Robin H. Johnson" <robbat2@g.o>
Re: [gentoo-dev] Documentation linkage or location Paul de Vrieze <pauldv@g.o>
Re: [gentoo-dev] Documentation linkage or location Donnie Berkholz <spyderous@g.o>