Gentoo Linux Documentation Policy
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 our documentation must go through prior to
dissemination on our website, or elsewhere.
This policy will cover the following topics:
- Documentation Project Team Organization
- Documentation Guidelines
- Documentation Team Recruitment
Documentation Project Team Organization
The Gentoo Documentation Project Team consists of editors and authors, working
on our main documentation and its translations. Like most other Gentoo projects,
it is led by a project lead whose additional job is to look after the team and
its resources in general (such as focusing on recruitment when necessary and
taking final decisions when consensus about doc-related issues cannot be found
When the Gentoo Documentation Team launches any subprojects, you will find its
mission on our GDP Project Webpage, along with
their respective project leads.
Documentation Project Team Members
Every member of the Gentoo Documentation Project must be subscribed to
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
firstname.lastname@example.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. Please do
not use this address to try and contact the team - you can contact us
through the mailinglist, IRC or by mailing the project lead or any other member.
Members of the Gentoo Documentation Team are frequently online in
#gentoo-doc on irc.freenode.net.
Depending on the assignment or responsibilities, a member may have CVS
access to cvs.gentoo.org. Interested non-developers can use the
anonymous CVS server
to help out with the documentation. It contains the same files as our CVS
server but is a few minutes late.
Documentation Translation Teams
Every language should be backed up by an official Translation Team. This
team is led by a Lead Translator and perhaps a Follow-On Lead
Translator, who both have CVS commit access. Organization of the
translations is handled by the lead translator as he or she sees fit, as
long as the committed translations follow this policy.
If a translated document for an unsupported language is contributed, the Gentoo
Documentation Team will publish it as-is. Such documents will not be linked to
the website until an official Translation Team of that language is formed, but
they will be available on our site and in CVS.
For more information Gentoo document translations, please consult the
Translators Howto for Gentoo Documentation and the
GDP Internationalisation Subproject page.
Gentoo Documentation Guidelines
Every document published by the Gentoo Documentation Project must be
licensed by the Creative Commons
Attribution-ShareAlike License, preferably the latest version (although
earlier versions are supported too).
Every document must have the following tag inside its GuideXML
source code between the </abstract> and the <version>
Code Listing 3.1: Licensing notice for the Gentoo Documentation
<!-- The content of this document is licensed under the CC-BY-SA license -->
<!-- See http://creativecommons.org/licenses/by-sa/3.0 -->
If the 2.5 version is used, the tag can be either <license /> or
<license version="2.5" />. In either case must the comment be
updated to refer to the correct version URL.
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.
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
email@example.com is on the Cc-list. A bug may not be taken
away from another Gentoo Documentation Team member without their approval
unless consent has been received from the project lead.
Every Gentoo Documentation Team may handle documentation development as it sees
fit. However, when the document is finished, it should be transformed into
GuideXML and made available on the
Gentoo CVS infrastructure. It must also be registered in the
metadoc.xml file if
When a new document is started or a big change is needed, a bug should be filed
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 HTML document changes.
Versions should always be handled as integers, so a version bump of version
2 leads to version 3. Historical versions that use the major and
minor syntax should be converted to the next integer on the next update, so
version 3.2 becomes version 4.
Every update of a translation should use the version and date information
verbatim from the master English document so fully synchronised translations
have the same version and date.
Reviewing and Committing
To maintain a high-paced documentation development cycle, technical or
intrusive changes to documents can be propagated immediately to the document.
This is allowed only if the editor is absolutely confident the changes
are functionally correct. If you are not absolutely confident (for instance because a
user has told you how to fix it but you cannot verify yourself), have the
changes reviewed by a third person that can verify the changes are apt.
High-volume, technical or intrusive changes must be accompanied by a bug report
on http://bugs.gentoo.org. This bug number must be mentioned
in the CVS log to allow backtracing of changes.
If a bugfix includes changes to content as well as internal coding changes,
both changes must be committed separately. This allows translators to focus
on the relevant changes regarding content and ignore the coding changes.
Malicious conduct by developers has not been an issue before. However, it
should be noted that 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
will be reported to the Gentoo Developer
Documentation Team Recruitment
Contributors, Authors, Translators
Everyone interested in contributing documentation, editing existing
documentation, writing new documentation or translating documentation is
welcome to send their contributions. There are no rules or strings attached to
this. Just make sure you are subscribed to firstname.lastname@example.org,
and you have fully read this policy and understand it.
The Documentation Project uses the recruitment process outlined below.
We have opted for this recruitment process to assure ourselves that the recruit
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 does not require developer access.
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 allow the contributor to find out
if he can provide continuous support for the Gentoo Documentation Project.
An update constitutes a non-trivial update to any documentation, translation or
otherwise, completely written or edited by the contributor and committed after
review by any existing documentation developer.
If you feel that you have shown sufficient amount of contributions, contact
the project lead of the Gentoo Documentation Project who will review the
contributions and the timeframe (or delegate this towards another GDP member).
He will ask you for your coordinates and other information, and
then arrange for the next phase to be started.
Phase 2: Start the Recruitment Process
During this period, submitted patches are not edited by a documentation
developer anymore, but are either committed as-is or refused. The recruit is
also assigned to a 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 tackled by the recruit himself with help of the
During this period, the recruit: is advised to learn about Gentoo's inner workings.
This is required as he or she will be asked later on to answer Gentoo's Staffing Quiz.
It is also recommended, but not automatically required, to fill in the Gentoo Documentation Project Quiz.
This will assist the recruit in learning more about how the Gentoo Documentation
Project documentation works. If at a later time the Gentoo Documentation Project
lead feels that the recruit (or by then editor or author) shows insufficient
knowledge on this, he might ask the recruit (or by then editor or author) to
work on the quiz after all.
Phase 3: Gentoo Recruitment
When Phase 2 is finished, the project lead will contact Developer Relations and give a final "Go!" for the
Gentoo recruitment process after which the recruit will be given access to the
necessary Gentoo infrastructural services (like the documentation repository).
Recruitment of Existing Gentoo Developers
If the recruit is already a Gentoo Developer, the same recruitment process is
followed, but of course the staffing quiz is not necessary anymore. The Gentoo Documentation Project Quiz is
The contents of this document, unless otherwise expressly stated, are licensed under the CC-BY-SA-2.5 license. The Gentoo Name and Logo Usage Guidelines apply.