swift 11/09/27 17:55:35
Update on GDP policy - Improve wording to work with current development process, drop references to old names, update recruitment process, update on translation management (reflecting as-is situation more)
Revision Changes Path
file : http://sources.gentoo.org/viewvc.cgi/gentoo/xml/htdocs/proj/en/gdp/doc/doc-policy.xml?rev=1.25&view=markup
diff : http://sources.gentoo.org/viewvc.cgi/gentoo/xml/htdocs/proj/en/gdp/doc/doc-policy.xml?r1=1.24&r2=1.25
RCS file: /var/cvsroot/gentoo/xml/htdocs/proj/en/gdp/doc/doc-policy.xml,v
retrieving revision 1.24
retrieving revision 1.25
diff -u -r1.24 -r1.25
--- doc-policy.xml 8 Nov 2010 22:54:00 -0000 1.24
+++ doc-policy.xml 27 Sep 2011 17:55:35 -0000 1.25
@@ -1,5 +1,5 @@
<?xml version='1.0' encoding="UTF-8"?>
-<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/proj/en/gdp/doc/doc-policy.xml,v 1.24 2010/11/08 22:54:00 nightmorph Exp $ -->
+<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/proj/en/gdp/doc/doc-policy.xml,v 1.25 2011/09/27 17:55:35 swift Exp $ -->
<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
@@ -26,8 +26,8 @@
<!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
@@ -39,7 +39,7 @@
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 <e>all</e> documentation must go through prior to
+guidelines that our documentation must go through prior to
dissemination on our website, or elsewhere.
@@ -70,68 +70,18 @@
-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.
+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 lead 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
+acting as an unbiased mediator when two or more developers have a dispute over
-The Gentoo Documentation Project is strategically led by a top-level Manager
-as required by the <uri link="/doc/en/management-structure.xml">Gentoo
-Management Structure</uri>. 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 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:
- <th>Developer Name</th>
- <th>Developer Nick</th>
- <ti>Strategic Manager</ti>
- <ti>Joshua Saddler</ti>
- <ti><mail link="email@example.com">nightmorph</mail></ti>
- <ti>Operational Manager</ti>
- <ti>Joshua Saddler</ti>
- <ti><mail link="firstname.lastname@example.org">nightmorph</mail></ti>
-Every subproject has a Strategic Manager of its own, and may have an
-Operational Manager if deemed appropriate. His responsibilities to the Gentoo
-Documentation Project (GDP) are listed in the <e>Manager responsibilities</e>
-section of the <uri
-Every subproject of the Gentoo Documentation Team is listed on the
-<uri link="/proj/en/gdp/">GDP Webpage</uri>, along with their respective
-The decision on adding a subproject is in the hands of the Strategic Manager.
+When the Gentoo Documentation Team launches any subprojects, you will find its
+mission on our <uri link="/proj/en/gdp/">GDP Project Webpage</uri>, along with
+their respective project leads.
@@ -153,21 +103,22 @@
<mail>email@example.com</mail> alias. This alias is <e>only</e> used by <uri
link="http://bugs.gentoo.org">bugs.gentoo.org</uri> to inform the documentation
team about bugs regarding the Gentoo Documentation. You can add yourself by
-editing <path>/var/mail/alias/misc/docs-team</path> on dev.gentoo.org.
+editing <path>/var/mail/alias/misc/docs-team</path> on dev.gentoo.org. Please do
+<e>not</e> 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 should be available at
-<c>#gentoo-doc</c> on <uri link="http://www.freenode.net">irc.freenode.net</uri>
-whenever they are online.
+Members of the Gentoo Documentation Team are frequently online in
+<c>#gentoo-doc</c> on <uri link="http://www.freenode.net">irc.freenode.net</uri>.
-Depending on the assignment or responsibilities, a member may have limited CVS
-access to <c>cvs.gentoo.org</c>. Full CVS access is restricted to Gentoo
-Developers. An <uri link="http://anoncvs.gentoo.org">anonymous CVS server</uri>
-is available. It contains the same files as our CVS server but is a few minutes
+Depending on the assignment or responsibilities, a member may have CVS
+access to <c>cvs.gentoo.org</c>. Interested non-developers can use the
+<uri link="http://anoncvs.gentoo.org">anonymous CVS server</uri>
+to help out with the documentation. It contains the same files as our CVS
+server but is a few minutes late.
@@ -179,10 +130,9 @@
Every language should be backed up by an official Translation Team. This
team is led by a <e>Lead Translator</e> and perhaps a <e>Follow-On Lead
-Translator</e>, who both have CVS commit access. If for any reason the
-<e>Lead Translator</e> cannot perform his duties, the <e>Follow-On Lead
-Translator</e> is in charge. If the <e>Follow-On</e> is unavailable, the
-mentor(s) is/are in charge of the language.
+Translator</e>, 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.
@@ -193,14 +143,6 @@
-When a language is officially supported, but the team does not have any
-members willing to take on the responsibilities of the <e>Lead
-Translator</e>, 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</uri> and the
@@ -253,17 +195,15 @@
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
<uri link="/proj/en/gdp/doc/metadoc-guide.xml">metadoc.xml</uri> 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
<mail>firstname.lastname@example.org</mail> 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.
+away from another Gentoo Documentation Team member without their approval
+unless consent has been received from the project lead.
@@ -304,8 +244,10 @@
-Whether or not to increment the major version number instead of minor version
-number or other is up to the editor.
+Versions should always be handled as integers, so a version bump of version
+<c>2</c> leads to version <c>3</c>. Historical versions that use the major and
+minor syntax should be converted to the next integer on the next update, so
+version <c>3.2</c> becomes version <c>4</c>.
@@ -324,9 +266,9 @@
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 <e>if</e> the editor is absolutely confident the changes
-are functional. If you are not absolutely confident (for instance because a
+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 Gentoo Developer that can verify the changes are apt.
+changes reviewed by a third person that can verify the changes are apt.
@@ -341,14 +283,6 @@
on the relevant changes regarding content and ignore the coding changes.
-If the document in question is a translation, the <e>Lead Translator</e> of the
-affected language is responsible for the document. Only the <e>Lead
-Translator</e> and his follow-on may commit the document to the CVS repository.
-However, if the <e>Lead Translator</e> is currently "in training", the
-trainee's mentor should commit the changes.
@@ -356,8 +290,8 @@
-Malicious conduct by developers has never been an issue. However, it should be
-noted that documentation developers that misuse their position by
+Malicious conduct by developers has not been an issue before. However, it
+should be noted that documentation developers that misuse their position by
@@ -368,10 +302,7 @@
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
+ <li>not performing at all for a long time without informing the GDP</li>
@@ -404,19 +335,17 @@
-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
+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 is granted by a simple request to the
-Operational Manager or Project Lead.
+a certain document or range of documents does not require developer access.
@@ -429,61 +358,21 @@
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.
+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.
-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
- <th>Minimal Activity</th>
- <th>Minimal Period</th>
- <ti>Full-time Developer</ti>
- <ti>2 updates per week</ti>
- <ti>1 month</ti>
- <ti>Part-time Developer</ti>
- <ti>4 updates per month</ti>
- <ti>1 month</ti>
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.
+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 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.
+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
@@ -493,34 +382,34 @@
-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
+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 refused.
+that affects the document is tackled by the recruit himself with help of the
-During this period, you:
+During this period, the recruit:
- are advised to learn about Gentoo's inner workings.
- This is required as you will be asked later on to answer Gentoo's <uri
+ 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 <uri
will be asked to fill in the <uri
link="/proj/en/gdp/doc/doc-quiz.xml">Gentoo Documentation Project
- Quiz</uri>. You need to successfully pass this entire quiz (all questions)
- before you can continue with the next Phase.
+ Quiz</uri>. He or she needs to successfully pass this entire quiz
+ (all questions) before we can continue with the next Phase.
@@ -531,10 +420,23 @@
-When Phase 2 is finished, the Operational Manager will contact <uri
+When Phase 2 is finished, the project lead will contact <uri
link="/proj/en/devrel/">Developer Relations</uri> 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.
+Gentoo recruitment process after which the recruit will be given access to the
+necessary Gentoo infrastructural services (like the documentation repository).
+<title>Recruitment of Existing Gentoo Developers</title>
+If the recruit is already a Gentoo Developer, the same recruitment process is
+followed, but the staffing quiz is not necessary anymore. However, the <uri
+link="/proj/en/gdp/doc/doc-quiz.xml">Gentoo Documentation Project Quiz</uri> is