Gentoo Linux Documentation Policy

1.  Introduction

Introduction

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 prior to dissemination on our website, or elsewhere.

Covered Topics

This policy will cover the following topics:

• Documentation Project Team Organization
• Documentation Guidelines
• Documentation Team Recruitment

2.  Documentation Project Team Organization

Organization

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

For day-to-day managerial tasks, the Gentoo Documentation Project has an Operational Manager. This person keeps track of all short-term tasks related to documentation. 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:

Every subproject of the Gentoo Documentation Team is listed on the GDP Webpage, along with their respective Strategic Managers.

The decision on adding a subproject is in the 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.

Members of the Gentoo Documentation Team should be available at #gentoo-doc on irc.freenode.net whenever they are online.

Depending on the assignment or responsibilities, a member may have limited CVS access to cvs.gentoo.org. Full CVS access is restricted to Gentoo Developers. An anonymous CVS server is available. 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. If for any reason the Lead Translator cannot perform his duties, the Follow-On Lead Translator is in charge. If the Follow-On is unavailable, the mentor(s) is/are in charge of the language.

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.

When a language is officially supported, but the team does not have any members willing 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.

For more information Gentoo document translations, please consult the Translators Howto for Gentoo Documentation and the GDP Internationalisation Subproject page.

3.  Gentoo Documentation Guidelines

Legal 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 source code 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.5 -->
<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 Strategic or Operational Manager may decide that a bug has a higher priority and should be addressed ahead any other task the assignee is responsible for.

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. A bug may not be taken away from another Gentoo Documentation Team member without their approval; unless consent has been received from the Operational Manager.

Document Development

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 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 HTML 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 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 functional. 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 Gentoo Developer 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.

If the document in question is a translation, the Lead Translator of the affected language is responsible for the document. Only the Lead Translator and his follow-on may commit the document to the CVS repository. However, if the Lead Translator is currently "in training", the trainee's mentor should commit the changes.

Sanctions

Malicious conduct by developers has never been an issue. 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, and without replying to the Operational Manager's request for a status update

will be reported to the Gentoo Developer Relations project.

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

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 aforementioned 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: Start the Recruitment Process

During this period, which is roughly the same as the aforementioned table, 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 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 successfully 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.

The contents of this document are licensed under the Creative Commons - Attribution / Share Alike license.