[gentoo-dev] Documentation linkage or location

[gentoo-dev] Documentation linkage or location

[Sven Vermeulen]

[-- 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 --]

Re: [gentoo-dev] Documentation linkage or location

[Robin H. Johnson]

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

On Thu, Oct 23, 2003 at 09:30:39AM +0200, Sven Vermeulen wrote:
> 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.
[snip]
(3) Strongly consider implementing CVS ACL's (as used by BSD projects,
PHP and others). This allows us to move the documents and improve on
existing access control, such as allowing all editors and project
members to have access to the documentation of a project.

-- 
Robin Hugh Johnson
E-Mail     : robbat2@orbis-terrarum.net
Home Page  : http://www.orbis-terrarum.net/?l=people.robbat2
ICQ#       : 30269588 or 41961639
GnuPG FP   : 11AC BA4F 4778 E3F6 E4ED  F38E B27B 944E 3488 4E85

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

Re: [gentoo-dev] Documentation linkage or location

[Sven Vermeulen]

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

On Thu, Oct 23, 2003 at 12:38:46AM -0700, Robin H. Johnson wrote:
> (3) Strongly consider implementing CVS ACL's (as used by BSD projects,
> PHP and others). This allows us to move the documents and improve on
> existing access control, such as allowing all editors and project
> members to have access to the documentation of a project.

I think it is still necessary to have a nice guideline on where certain
documentation is stored. Paul's proposal on having user documentation in
doc/, while developer documentation can be elsewhere (divided amongst the
related projects) is a nice idea which I can support.

The CVS ACLs can then be used to finetune permissions (which I also
encourage, both for security reasons as for managerial reasons). 

By having all user documentation in doc/, translations are easily integrated.
Development-related documentation doesn't really need translations (my
opinion) and is therefor "safe" to reside in the project-specific structures.

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 --]

Re: [gentoo-dev] Documentation linkage or location

[Paul de Vrieze]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

I think we might consider a split on documentation target

On Thursday 23 October 2003 09:30, Sven Vermeulen wrote:
> (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.

Developer related documentation can go here, however we need to get some 
good procedure for publishing links to these documents in an index.

>
> (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.
>

User documentation should go here. It is more critical on correctness and 
readability. It probably also creates more confusion if it not 
maintained by documentation.

> 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)?

For user related docs not at all. I think that developer related 
documentation (esp. that which is still in state of development) can 
stay in the project directories. However I agree with robbat2 on 
exploring ACL's

Paul

- -- 
Paul de Vrieze
Gentoo Developer
Mail: pauldv@gentoo.org
Homepage: http://www.devrieze.net
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.2.3 (GNU/Linux)

iD8DBQE/l5Z1bKx5DBjWFdsRArSFAJ4qapZKiLAxHSp8XmbgpsopaHH2hACfYTPW
JlOYnwo2infMW7tijv3/5mY=
=vrCM
-----END PGP SIGNATURE-----


--
gentoo-dev@gentoo.org mailing list

Re: [gentoo-dev] Documentation linkage or location

[Donnie Berkholz]

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

On Thu, 2003-10-23 at 03:30, Sven Vermeulen wrote:
> (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)?

As long as you add me as the Project Doc Editor for cluster, I'm in
agreement. The only (or at least best) reason things were staying in
proj/en/cluster/ was to avoid having more middlemen.

[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 189 bytes --]

Re: [gentoo-dev] Documentation linkage or location

[Sven Vermeulen]

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

On Thu, Oct 23, 2003 at 05:52:23AM -0400, Donnie Berkholz wrote:
> As long as you add me as the Project Doc Editor for cluster, I'm in
> agreement. The only (or at least best) reason things were staying in
> proj/en/cluster/ was to avoid having more middlemen.

You'll have one middlemen, namely the person that reviews your change(s).
This happens quite fast though, and if the update is really necessary
(system b0rkage) you can even commit without reviewing.

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 --]

Re: [gentoo-dev] Documentation linkage or location

[donnie berkholz]

> On Thu, Oct 23, 2003 at 05:52:23AM -0400, Donnie Berkholz wrote:
>> As long as you add me as the Project Doc Editor for cluster, I'm in
>> agreement. The only (or at least best) reason things were staying in
>> proj/en/cluster/ was to avoid having more middlemen.
>
> You'll have one middlemen, namely the person that reviews your
> change(s). This happens quite fast though, and if the update is really
> necessary (system b0rkage) you can even commit without reviewing.

My understanding of the Project Doc Editor's role is that he has authority
to review and commit changes of docs in that project. Am I
misunderstanding that role?



--
gentoo-dev@gentoo.org mailing list

Re: [gentoo-dev] Documentation linkage or location

[Sven Vermeulen]

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

On Thu, Oct 23, 2003 at 01:09:21PM -0400, donnie berkholz wrote:
> My understanding of the Project Doc Editor's role is that he has authority
> to review and commit changes of docs in that project. Am I
> misunderstanding that role?

The Project Doc Editor is the developer who will take on bugreports
on the documentation of his (or her) project in case technical changes are
needed. He is a full member of the documentation team, but doesn't have to do
documentation editing for other documents (although he is free to do so).

When a patch is created, independent of who made the patch and why, it must
be reviewed by a second person (a gentoo developer) to check for
inconsistencies, other errors and such. This reviewing step is mandatory
unless:
	- the patch must be applied asap because the current documentation
	  breaks systems
	- the patch is to fix grammatical issues or typos

In some cases, this means a one-man job (if the bugreport already has a
patch, then he (or she) can review the patch and commit); in most cases you
write up a patch and attach it to the bugreport. One of our editors will then
verify the patch and state (as a comment on the bugreport) that the patch is
fine (or something with the same meaning :)

The documentation team works by the documentation policy [1], although a new
change [2] on that policy which removes some difficulties is waiting.

Wkr,
	Sven Vermeulen

[1] http://www.gentoo.org/doc/en/doc-policy.xml
[2] http://emu.gentoo.org/~swift/doc-policy.html

-- 
 ^__^   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 --]