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:
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 otherwise).
When the Gentoo Documentation Team launches any subprojects, you will find its
mission on our
Every member of the Gentoo Documentation Project must be subscribed to
the
Every member of the Gentoo Documentation Project must be part of the
Members of the Gentoo Documentation Team are frequently online in
Depending on the assignment or responsibilities, a member may have CVS
access to
Every language should be backed up by an official Translation Team. This
team is led by a
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
Every document published by the Gentoo Documentation Project must be
licensed by the
Every document must have the following tag inside its GuideXML
source code between the
</abstract> <!-- The content of this document is licensed under the CC-BY-SA license --> <!-- See http://creativecommons.org/licenses/by-sa/3.0 --> <license version="3.0"/> <version>...</version>
If the 2.5 version is used, the tag can be either
Every bug reported on
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
Every Gentoo Documentation Team may handle documentation development as it sees
fit. However, when the document is finished, it should be transformed into
When a new document is started or a big change is needed, a bug should be filed
at
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
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.
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
High-volume, technical or intrusive changes must be accompanied by a bug report
on
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
will be reported to the
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
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.
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. He will ask you for your coordinates and other information, and then arrange for the next phase to be started.
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 mentor.
During this period, the recruit:
When Phase 2 is finished, the project lead will contact
If the recruit is already a Gentoo Developer, the same recruitment process is
followed, but the staffing quiz is not necessary anymore. However, the