Gentoo Linux Documentation PolicyJohn P. DavisSven VermeulenDonnie Berkholz
This document contains the Gentoo Documentation Policy, which is the
base document which all Gentoo Documentation developers and
Contributers should know and exercise.
3.112005-05-07IntroductionIntroduction

The Gentoo Linux Documentation team aspires to create exceptionally
professional documentation that is immediately clear and concise to the
end user. In order to fulfill this goal, we have very specific rules and
guidelines that all documentation must go through before it is
published on our website, or otherwise.

Covered Topics

This policy will cover these topics:

Documentation Project Team Organization

Documentation Guidelines

Documentation Team Recruitement

Documentation Project Team OrganizationOrganization

The Gentoo Documentation Project Team is split into several smaller teams
that operate in complete cooperation with each other. Each smaller team
represents an active development team of a Gentoo Documentation
Subproject.

The Gentoo Documentation Project is strategically lead by a top-level manager
as required by the Gentoo
Management Structure. This document also describes the responsibilities
of the strategic manager with respect to Gentoo Linux.

For day-to-day managerial tasks the Gentoo Documentation Project has an
operational manager. This person keeps track of all documentation-related tasks
that are more short-term. The operational manager and strategic manager can be
one and the same if the strategic manager wishes so.

Currently these positions are taken by the following people:

Position

Developer Name

Developer Nick

Strategic ManagerSven Vermeulenswift

Operational ManagerXavier Neysneysx

Every subproject has a strategic manager of its own. he can have an operational
manager if he deems appropriate. His responsibilities to the Gentoo
Documentation Project are the same as are listed on the Gentoo Management
Structure.

The subprojects of the Gentoo Documentation Team together with their respective
strategic managers are listed on the GDP
Website.

The decision on adding subprojects is in hands of the strategic manager.

Documentation Project Team Members

Every member of the Gentoo Documentation Project must be subscribed to
the gentoo-doc@gentoo.org
mailing list. This mailing list will be used to discuss all
documentation-related issues. This mailing list is open to all interested
parties, developer or not.

Every member of the Gentoo Documentation Project must be part of the
docs-team@gentoo.org alias. This
alias is only used by bugs.gentoo.org to inform the documentation
team about bugs regarding the Gentoo Documentation. You can add yourself by
editing /var/mail/alias/misc/docs-team on dev.gentoo.org.

Every member of the Gentoo Documentation Team should be available at
#gentoo-doc on irc.freenode.net
whenever he is online.

Depending on his responsibilities, he can have limited CVS
access to cvs.gentoo.org. Full CVS access can only be given to Gentoo
developers. Read-only CVS access can be given to recruitees.

Documentation Translation Teams

Every language should be backed up by an official translation team. This
team is lead by a lead translator and perhaps a follow-up lead translator, who
both have CVS commit access. If for any reason the lead translator cannot
perform his or her duties, the follow-up lead translator is in charge. If
even this person is unavailable, the mentor(s) is/are in charge of the language.

If a translated document is contributed, but the language in itself is
not supported, the Gentoo Documentation Team will not publish it
officially. In this case the document will stay unlinked until an official
translation team of that language is formed.

When a language is officially supported, but the team doesn't have any
members or no one wants to take on the responsibilities of the lead
translator, all links to the documents will be removed from the site.
However, the documents will stay available in case the language becomes
officially supported again.

Gentoo Documentation GuidelinesLegal Issues

Every document published by the Gentoo Documentation Project must be
licensed by the Creative Commons
Attribution-ShareAlike License.

Every document must have the following tag inside its GuideXML
sourcecode between the </abstract> and the <version>
tags:

</abstract>
<!-- The content of this document is licensed under the CC-BY-SA license -->
<!-- See http://creativecommons.org/licenses/by-sa/2.0 -->
<license/>
<version>...</version>

Bugs and Updates

Every bug reported on bugs.gentoo.org
should be handled as fast as possible. If a bug cannot be handled
in a timely fashion, the reporter of that bug should be informed about
this using a comment on the bug and the bug should be registered in the
metadoc.xml file, if
applicable. The tactical or operational manager can decide that a bug has a
higher priority and should be handled first before any other task the assingee
is responsible of.

Whenever a Gentoo Documentation Team member takes care of a bug, he or
she should assign the bug to herself/himself, but make sure that
docs-team@gentoo.org is on the Cc-list. Unless with the consent
of the operational manager, a bug may not be taken away from another
Gentoo Documentation Team member without their approval.

Document Development

Every document the Gentoo Documentation Team develops can be developed as the
related parties see fit. However, when the document is finished, it should be
transformed into GuideXML and put
available on the Gentoo CVS infrastructure. It must also be registered in the
metadoc.xml file if
applicable.

When a new document is started or a big change is needed, a bug should be filed
at bugs.gentoo.org
concerning the development of this document. If there is already a bug
in the database that requests a change to the documentation, a new bug
does not have to be filed. Grammatical, syntactical or small changes
do not require a bug to be filed on bugs.gentoo.org as well.

All changes in contents of the document, except for typo fixes in text
itself or in the comments to code listings, should lead to version
number (and date) increase. Note that the change of a Code Listings should
definitely cause an increase of the version number and date.

All changes in XML formatting should lead to version (and date) bumps only in
case the layout of the document changes.

Whether or not to increment the major version number instead of minor version
number or other is up to the editor.

Every update of a translation should copy the new version information
verbatim from the master English document so fully synchronised
translations have the same version information.

Reviewing and Committing

To keep a high-pace development cycle of the documentation, technical or
intrusive changes to documents can be propagated immediately to the document
if the editor is 100% confident his changes are correct and working. If
you are not 100% confident (for instance because a user has told you how to fix
it but you cannot verify yourself), have the change reviewed by a Gentoo
Developer that can verify the change.

High volume, technical or intrusive changes must be accompanied by a bugreport
on http://bugs.gentoo.org. This bugnumber must be mentioned in
the CVS log to allow backtracing of changes.

If a bugfix consists out of both content as internal coding changes,
both changes must be committed separately so that translators can easily
view the important changes (content) and ignore the coding changes.

In case of a translation, the lead translator of the language is
responsible for the document. Only he may commit the document to CVS
unless he is currently "in training", in which case his or her
mentor should commit it.

Sanctions

Although this has never been necessary, it is still important to list this in
the policy - even though it is hateful. Anyway, documentation developers that
misuse their position by

deliberately providing wrong information to users or developers

deliberately writing flawed documentation

deliberately corrupting documents

deliberately go against the decisions made policy-wise or through a
consensus-model on the Gentoo Documentation mailinglist

not performing at all for a long time without informing the GDP and without
replying to the operational manager's request for a status update

will be reported to the Gentoo Developer
Relations project.

Documentation Team RecruitementContributors, Authors, Translators

Everyone interested in contributing documentation, editing existing
documentation, writing new documentation or translating documentation is
welcome to join the team. There are no rules or strings attached to
this. Just make sure you are subscribed to gentoo-doc@gentoo.org
and you have fully read this policy and understand it.

Recruitment Process

The Documentation Project has a strict recruitment process outlined below.
This process can not be deviated from in any circumstance. We have opted for
this recruitment process to assure ourselves that the recruitee is well informed
about the Gentoo Documentation Policy and the Gentoo Coding Style. It has proven
to be quite effective even though many contributors see it as a too large burden
to cross.

This recruitment process is meant only for requests to the Gentoo Documentation
Repository through CVS. Being listed as the maintainer or Point-Of-Contact for a
certain document or range of documents is granted by a simple request to the
Operational Manager or Project Lead.

Phase 1: Contributions

No recruitment process starts without investigating the contributions done
already to the Gentoo Documentation Project. The number of contributions must be
large to assure a good knowledge of GuideXML, Coding Style and policy. The
contribution period must be large as well to inform the contributor about the
time-consuming position and pressure the application involves.

The number of contributions and period over which the contributions should be
made depends on the position which the contributor solicits for. Although it is
difficult to write down these measurements in numbers, the following table
should give a general overview. Final decision however lays in the hands of the
Operational Manager.

Position

Minimal Activity

Minimal Period

Full-time Developer2 updates per week1 months

Part-time Developer4 updates per month1 months

An update constitutes a non-trivial update to any documentation, translation or
otherwise, completely written by the contributor and committed after review by
any existing documentation developer. The period is fixed - increasing the
contributions does not decrease the period. Also, we don't average the
contributions over time to make sure the contributor doesn't give a contribution
burst and then waits until the Phase is over.

Without this phase we can not know if the contributor understands what it takes
to be a documentation developer. The validation of this activity happens through
bugzilla reports.

Any request for CVS access that does not allow a development activity as written
down in the abovementioned table will not be taken into account.

If you feel that you have shown sufficient amount of contributions, contact
the Operational Manager of the Gentoo Documentation Project. He
will ask you for your coordinates and other information and then arrange
for the next phase to be started.

Phase 2: Read-Only CVS Access

During phase 2, the recruitee is given read-only access to the Gentoo
Documentation Repository, allowing him to generate commit-ready patches for the
tree. During this period, which is roughly the same as the abovementioned table,
his patches are not edited by a documentation developer anymore, but are either
committed as-is or refused. The recruitee is also assigned to a full-time
documentation developer (the mentor) which will guide him through these last
phases.

The quality of the contributions are in this phase most important - every patch
that does not follow the Documentation Policy, Coding Style or other guideline
that affects the document is refused.

During this period, you:

are advised to learn about Gentoo's inner workings.
This is required as you will be asked later on to answer Gentoo's Staffing Quiz.

will be asked to fill in the Gentoo Documentation Project
Quiz. You need to succesfully pass this entire quiz (all questions)
before you can continue with the next Phase.

Phase 3: Gentoo Recruitment

When Phase 2 is finished, the Operational Manager will contact Developer Relations and give a final "Go!" for the
Gentoo recruitment process after which you will be given a Gentoo e-mail
address and be appointed to one or more subprojects.