gdp/doc/doc-policy.xml

<?xml version='1.0' encoding="UTF-8"?>
<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/proj/en/gdp/doc/doc-policy.xml,v 1.12 2005/05/12 09:56:52 neysx Exp $ -->

<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">

<guide link="doc-policy.xml">

<title>Gentoo Linux Documentation Policy</title>
<author title="Author">
    <mail link="zhen@gentoo.org">John P. Davis</mail>
</author>
<author title="Author">
    <mail link="swift@gentoo.org">Sven Vermeulen</mail>
</author>
<author title="Editor">
    <mail link="spyderous@gentoo.org">Donnie Berkholz</mail>
</author>

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

<abstract>
This document contains the Gentoo Documentation Policy, which is the
base document which all Gentoo Documentation developers and
Contributers should know and exercise.
</abstract>

<license/>

<version>3.11</version>
<date>2005-05-07</date>

<chapter>
<title>Introduction</title>
<section>
<title>Introduction</title>
<body>

<p>
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 
dissemination on our website, or otherwise.
</p>

</body>
</section>
<section>
<title>Covered Topics</title>
<body>

<p>
This policy will cover the following topics: 
</p>

<ul>
<li>Documentation Project Team Organization</li>
<li>Documentation Guidelines</li>
<li>Documentation Team Recruitment</li>
</ul>

</body>
</section>
</chapter>

<chapter>
<title>Documentation Project Team Organization</title>
<section>
<title>Organization</title>
<body>

<p>
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.
</p>

<p>
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.
</p>

<p>
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.
</p>

<p>
Currently these positions are taken by the following people:
</p>

<table>
<tr>
  <th>Position</th>
  <th>Developer Name</th>
  <th>Developer Nick</th>
</tr>
<tr>
  <ti>Strategic Manager</ti>
  <ti>Sven Vermeulen</ti>
  <ti><mail link="swift@gentoo.org">swift</mail></ti>
</tr>
<tr>
  <ti>Operational Manager</ti>
  <ti>Xavier Neys</ti>
  <ti><mail link="neysx@gentoo.org">neysx</mail></ti>
</tr>
</table>

<p>
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 are the same as are listed on the <uri
link="/doc/en/management-structure.xml#doc_chap1_sect5">Gentoo Management
Structure</uri>.
</p>

<p>
The subprojects of the Gentoo Documentation Team together with their respective
strategic managers are listed on the <uri link="/proj/en/gdp/">GDP
Website</uri>. 
</p>

<p>
The decision on adding subprojects is in hands of the strategic manager. 
</p>

</body>
</section>
<section>
<title>Documentation Project Team Members</title>
<body>

<p>
Every member of the Gentoo Documentation Project must be subscribed to
the <mail link="gentoo-doc-subscribe@gentoo.org">gentoo-doc@gentoo.org</mail>
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.
</p>

<p>
Every member of the Gentoo Documentation Project must be part of the
<mail link="docs-team@gentoo.org">docs-team@gentoo.org</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.
</p>

<p>
Every member 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 he is online. 
</p>

<p>
Depending on his responsibilities, he can have limited CVS 
access to <c>cvs.gentoo.org</c>. Full CVS access can only be given to Gentoo
developers. Read-only CVS access can be given to recruits.
</p>

</body>
</section>
<section>
<title>Documentation Translation Teams</title>
<body>

<p>
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.
</p>

<p>
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.
</p>

<p>
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.
</p>

</body>
</section>
</chapter>

<chapter>
<title>Gentoo Documentation Guidelines</title>
<section>
<title>Legal Issues</title>
<body>

<p>
Every document published by the Gentoo Documentation Project must be
licensed by the <uri 
link="http://creativecommons.org/licenses/by-sa/2.0/">Creative Commons 
Attribution-ShareAlike License</uri>. 
</p>

<p>
Every document must have the following tag inside its GuideXML
source code between the <c>&lt;/abstract&gt;</c> and the <c>&lt;version&gt;</c>
tags:
</p>

<pre caption = "Licensing notice for the Gentoo Documentation">
&lt;/abstract&gt;
<i>
&lt;!-- The content of this document is licensed under the CC-BY-SA license --&gt;
&lt;!-- See http://creativecommons.org/licenses/by-sa/2.0 --&gt;
&lt;license/&gt;
</i>
&lt;version&gt;...&lt;/version&gt;
</pre>

</body>
</section>
<section>
<title>Bugs and Updates</title>
<body>

<p>
Every bug reported on <uri link="http://bugs.gentoo.org">bugs.gentoo.org</uri>
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 
<uri link="/proj/en/gdp/doc/metadoc-guide.xml">metadoc.xml</uri> file, if 
applicable. The tactical or operational manager may decide that a bug has a
higher priority and should be addressed ahead any other task the assingee
is responsible of.
</p>

<p>
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
<c>docs-team@gentoo.org</c> 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.
</p>

</body>
</section>
<section>
<title>Document Development</title>
<body>

<p>
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 <uri link="/doc/en/xml-guide.xml">GuideXML</uri> and put
available on the Gentoo CVS infrastructure. It must also be registered in the
<uri link="/proj/en/gdp/doc/metadoc-guide.xml">metadoc.xml</uri> file if
applicable.
</p>

<p>
When a new document is started or a big change is needed, a bug should be filed 
at <uri link="http://bugs.gentoo.org">bugs.gentoo.org</uri>
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 <uri 
link="http://bugs.gentoo.org">bugs.gentoo.org</uri> as well.
</p>

<p>
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.
</p>

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

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

<p>
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.
</p>

</body>
</section>
<section>
<title>Reviewing and Committing</title>
<body>

<p>
To keep a high-pace development cycle of the documentation, technical or
intrusive changes to documents can be propagated immediately to the document
<e>if</e> 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.
</p>

<p>
High volume, technical or intrusive changes must be accompanied by a bugreport 
on <uri>http://bugs.gentoo.org</uri>. This bug number <e>must</e> be mentioned 
in the CVS log to allow backtracing of changes.
</p>

<p>
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.
</p>

<p>
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.
</p>

</body>
</section>
<section>
<title>Sanctions</title>
<body>

<p>
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
</p>

<ul>
  <li>deliberately providing wrong information to users or developers</li>
  <li>deliberately writing flawed documentation</li>
  <li>deliberately corrupting documents</li>
  <li>
    deliberately go against the decisions made policy-wise or through a
    consensus-model on the Gentoo Documentation mailinglist
  </li>
  <li>
    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>
</ul>

<p>
will be reported to the <uri link="/proj/en/devrel/">Gentoo Developer
Relations</uri> project.
</p>

</body>
</section>
</chapter>

<chapter>
<title>Documentation Team Recruitement</title>
<section>
<title>Contributors, Authors, Translators</title>
<body>

<p>
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 <c>gentoo-doc@gentoo.org</c>
and you have fully read this policy and understand it.
</p>

</body>
</section>
<section>
<title>Recruitment Process</title>
<body>

<p>
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.
</p>

<p>
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.
</p>

</body>
</section>
<section>
<title>Phase 1: Contributions</title>
<body>

<p>
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.
</p>

<p>
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.
</p>

<table>
<tr>
  <th>Position</th>
  <th>Minimal Activity</th>
  <th>Minimal Period</th>
</tr>
<tr>
  <ti>Full-time Developer</ti>
  <ti>2 updates per week</ti>
  <ti>1 month</ti>
</tr>
<tr>
  <ti>Part-time Developer</ti>
  <ti>4 updates per month</ti>
  <ti>1 month</ti>
</tr>
</table>

<p>
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.
</p>

<p>
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.
</p>

<p>
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.
</p>

<p>
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.
</p>

</body>
</section>
<section>
<title>Phase 2: Read-Only CVS Access</title>
<body>

<p>
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 aforementioned table,
his 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.
</p>

<p>
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.
</p>

<p>
During this period, you:
</p>

<ul>
  <li>
    are advised to learn about Gentoo's inner workings. 
    This is required as you will be asked later on to answer Gentoo's <uri
    link="/proj/en/devrel/quiz/staff-quiz.txt">Staffing Quiz</uri>.
  </li>
  <li>
    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.
  </li>
</ul>

</body>
</section>
<section>
<title>Phase 3: Gentoo Recruitment</title>
<body>

<p>
When Phase 2 is finished, the Operational Manager 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. 
</p>

</body>
</section>
</chapter>
</guide>
1	<?xml version='1.0' encoding="UTF-8"?>
2	<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/proj/en/gdp/doc/doc-policy.xml,v 1.12 2005/05/12 09:56:52 neysx Exp $ -->
3
4	<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
5
6	<guide link="doc-policy.xml">
7
8	<title>Gentoo Linux Documentation Policy</title>
9	<author title="Author">
10	<mail link="zhen@gentoo.org">John P. Davis</mail>
11	</author>
12	<author title="Author">
13	<mail link="swift@gentoo.org">Sven Vermeulen</mail>
14	</author>
15	<author title="Editor">
16	<mail link="spyderous@gentoo.org">Donnie Berkholz</mail>
17	</author>
18
19	<!-- The content of this document is licensed under the CC-BY-SA license -->
20	<!-- See http://creativecommons.org/licenses/by-sa/2.0 -->
21
22	<abstract>
23	This document contains the Gentoo Documentation Policy, which is the
24	base document which all Gentoo Documentation developers and
25	Contributers should know and exercise.
26	</abstract>
27
28	<license/>
29
30	<version>3.11</version>
31	<date>2005-05-07</date>
32
33	<chapter>
34	<title>Introduction</title>
35	<section>
36	<title>Introduction</title>
37	<body>
38
39	<p>
40	The Gentoo Linux Documentation team aspires to create exceptionally
41	professional documentation that is immediately clear and concise to the
42	end user. In order to fulfill this goal, we have very specific rules and
43	guidelines that <e>all</e> documentation must go through prior to
44	dissemination on our website, or otherwise.
45	</p>
46
47	</body>
48	</section>
49	<section>
50	<title>Covered Topics</title>
51	<body>
52
53	<p>
54	This policy will cover the following topics:
55	</p>
56
57	<ul>
58	<li>Documentation Project Team Organization</li>
59	<li>Documentation Guidelines</li>
60	<li>Documentation Team Recruitment</li>
61	</ul>
62
63	</body>
64	</section>
65	</chapter>
66
67	<chapter>
68	<title>Documentation Project Team Organization</title>
69	<section>
70	<title>Organization</title>
71	<body>
72
73	<p>
74	The Gentoo Documentation Project Team is split into several smaller teams
75	that operate in complete cooperation with each other. Each smaller team
76	represents an active development team of a Gentoo Documentation
77	Subproject.
78	</p>
79
80	<p>
81	The Gentoo Documentation Project is strategically led by a top-level manager
82	as required by the <uri link="/doc/en/management-structure.xml">Gentoo
83	Management Structure</uri>. This document also describes the responsibilities
84	of the strategic manager with respect to Gentoo Linux.
85	</p>
86
87	<p>
88	For day-to-day managerial tasks, the Gentoo Documentation Project has an
89	operational manager. This person keeps track of all documentation-related tasks
90	that are more short-term. The operational manager and strategic manager can be
91	one and the same if the strategic manager wishes so.
92	</p>
93
94	<p>
95	Currently these positions are taken by the following people:
96	</p>
97
98	<table>
99	<tr>
100	<th>Position</th>
101	<th>Developer Name</th>
102	<th>Developer Nick</th>
103	</tr>
104	<tr>
105	<ti>Strategic Manager</ti>
106	<ti>Sven Vermeulen</ti>
107	<ti><mail link="swift@gentoo.org">swift</mail></ti>
108	</tr>
109	<tr>
110	<ti>Operational Manager</ti>
111	<ti>Xavier Neys</ti>
112	<ti><mail link="neysx@gentoo.org">neysx</mail></ti>
113	</tr>
114	</table>
115
116	<p>
117	Every subproject has a strategic manager of its own and may have an
118	Operational Manager if deemed appropriate. His responsibilities to the Gentoo
119	Documentation Project are the same as are listed on the <uri
120	link="/doc/en/management-structure.xml#doc_chap1_sect5">Gentoo Management
121	Structure</uri>.
122	</p>
123
124	<p>
125	The subprojects of the Gentoo Documentation Team together with their respective
126	strategic managers are listed on the <uri link="/proj/en/gdp/">GDP
127	Website</uri>.
128	</p>
129
130	<p>
131	The decision on adding subprojects is in hands of the strategic manager.
132	</p>
133
134	</body>
135	</section>
136	<section>
137	<title>Documentation Project Team Members</title>
138	<body>
139
140	<p>
141	Every member of the Gentoo Documentation Project must be subscribed to
142	the <mail link="gentoo-doc-subscribe@gentoo.org">gentoo-doc@gentoo.org</mail>
143	mailing list. This mailing list will be used to discuss all
144	documentation-related issues. This mailing list is open to all interested
145	parties, developer or not.
146	</p>
147
148	<p>
149	Every member of the Gentoo Documentation Project must be part of the
150	<mail link="docs-team@gentoo.org">docs-team@gentoo.org</mail> alias. This
151	alias is <e>only</e> used by <uri
152	link="http://bugs.gentoo.org">bugs.gentoo.org</uri> to inform the documentation
153	team about bugs regarding the Gentoo Documentation. You can add yourself by
154	editing <path>/var/mail/alias/misc/docs-team</path> on dev.gentoo.org.
155	</p>
156
157	<p>
158	Every member of the Gentoo Documentation Team should be available at
159	<c>#gentoo-doc</c> on <uri link="http://www.freenode.net">irc.freenode.net</uri>
160	whenever he is online.
161	</p>
162
163	<p>
164	Depending on his responsibilities, he can have limited CVS
165	access to <c>cvs.gentoo.org</c>. Full CVS access can only be given to Gentoo
166	developers. Read-only CVS access can be given to recruits.
167	</p>
168
169	</body>
170	</section>
171	<section>
172	<title>Documentation Translation Teams</title>
173	<body>
174
175	<p>
176	Every language should be backed up by an official translation team. This
177	team is lead by a lead translator and perhaps a follow-up lead translator, who
178	both have CVS commit access. If for any reason the lead translator cannot
179	perform his or her duties, the follow-up lead translator is in charge. If
180	even this person is unavailable, the mentor(s) is/are in charge of the language.
181	</p>
182
183	<p>
184	If a translated document is contributed, but the language in itself is
185	not supported, the Gentoo Documentation Team will not publish it
186	officially. In this case the document will stay unlinked until an official
187	translation team of that language is formed.
188	</p>
189
190	<p>
191	When a language is officially supported, but the team doesn't have any
192	members or no one wants to take on the responsibilities of the lead
193	translator, all links to the documents will be removed from the site.
194	However, the documents will stay available in case the language becomes
195	officially supported again.
196	</p>
197
198	</body>
199	</section>
200	</chapter>
201
202	<chapter>
203	<title>Gentoo Documentation Guidelines</title>
204	<section>
205	<title>Legal Issues</title>
206	<body>
207
208	<p>
209	Every document published by the Gentoo Documentation Project must be
210	licensed by the <uri
211	link="http://creativecommons.org/licenses/by-sa/2.0/">Creative Commons
212	Attribution-ShareAlike License</uri>.
213	</p>
214
215	<p>
216	Every document must have the following tag inside its GuideXML
217	source code between the <c></abstract></c> and the <c><version></c>
218	tags:
219	</p>
220
221	<pre caption = "Licensing notice for the Gentoo Documentation">
222	</abstract>
223	<i>
224	<!-- The content of this document is licensed under the CC-BY-SA license -->
225	<!-- See http://creativecommons.org/licenses/by-sa/2.0 -->
226	<license/>
227	</i>
228	<version>...</version>
229	</pre>
230
231	</body>
232	</section>
233	<section>
234	<title>Bugs and Updates</title>
235	<body>
236
237	<p>
238	Every bug reported on <uri link="http://bugs.gentoo.org">bugs.gentoo.org</uri>
239	should be handled as fast as possible. If a bug cannot be handled
240	in a timely fashion, the reporter of that bug should be informed about
241	this using a comment on the bug and the bug should be registered in the
242	<uri link="/proj/en/gdp/doc/metadoc-guide.xml">metadoc.xml</uri> file, if
243	applicable. The tactical or operational manager may decide that a bug has a
244	higher priority and should be addressed ahead any other task the assingee
245	is responsible of.
246	</p>
247
248	<p>
249	Whenever a Gentoo Documentation Team member takes care of a bug, he or
250	she should assign the bug to herself/himself, but make sure that
251	<c>docs-team@gentoo.org</c> is on the Cc-list. Unless with the consent
252	of the operational manager, a bug may not be taken away from another
253	Gentoo Documentation Team member without their approval.
254	</p>
255
256	</body>
257	</section>
258	<section>
259	<title>Document Development</title>
260	<body>
261
262	<p>
263	Every document the Gentoo Documentation Team develops can be developed as the
264	related parties see fit. However, when the document is finished, it should be
265	transformed into <uri link="/doc/en/xml-guide.xml">GuideXML</uri> and put
266	available on the Gentoo CVS infrastructure. It must also be registered in the
267	<uri link="/proj/en/gdp/doc/metadoc-guide.xml">metadoc.xml</uri> file if
268	applicable.
269	</p>
270
271	<p>
272	When a new document is started or a big change is needed, a bug should be filed
273	at <uri link="http://bugs.gentoo.org">bugs.gentoo.org</uri>
274	concerning the development of this document. If there is already a bug
275	in the database that requests a change to the documentation, a new bug
276	does not have to be filed. Grammatical, syntactical or small changes
277	do not require a bug to be filed on <uri
278	link="http://bugs.gentoo.org">bugs.gentoo.org</uri> as well.
279	</p>
280
281	<p>
282	All changes in contents of the document, except for typo fixes in text
283	itself or in the comments to code listings, should lead to version
284	number (and date) increase. Note that the change of a Code Listings should
285	definitely cause an increase of the version number and date.
286	</p>
287
288	<p>
289	All changes in XML formatting should lead to version (and date) bumps only in
290	case the layout of the document changes.
291	</p>
292
293	<p>
294	Whether or not to increment the major version number instead of minor version
295	number or other is up to the editor.
296	</p>
297
298	<p>
299	Every update of a translation should copy the new version information
300	verbatim from the master English document so fully synchronised
301	translations have the same version information.
302	</p>
303
304	</body>
305	</section>
306	<section>
307	<title>Reviewing and Committing</title>
308	<body>
309
310	<p>
311	To keep a high-pace development cycle of the documentation, technical or
312	intrusive changes to documents can be propagated immediately to the document
313	<e>if</e> the editor is 100% confident his changes are correct and working. If
314	you are not 100% confident (for instance because a user has told you how to fix
315	it but you cannot verify yourself), have the change reviewed by a Gentoo
316	Developer that can verify the change.
317	</p>
318
319	<p>
320	High volume, technical or intrusive changes must be accompanied by a bugreport
321	on <uri>http://bugs.gentoo.org</uri>. This bug number <e>must</e> be mentioned
322	in the CVS log to allow backtracing of changes.
323	</p>
324
325	<p>
326	If a bugfix consists out of both content as internal coding changes,
327	both changes must be committed separately so that translators can easily
328	view the important changes (content) and ignore the coding changes.
329	</p>
330
331	<p>
332	In case of a translation, the lead translator of the language is
333	responsible for the document. Only he may commit the document to CVS
334	unless he is currently "in training", in which case his or her
335	mentor should commit it.
336	</p>
337
338	</body>
339	</section>
340	<section>
341	<title>Sanctions</title>
342	<body>
343
344	<p>
345	Although this has never been necessary, it is still important to list this in
346	the policy - even though it is hateful. Anyway, documentation developers that
347	misuse their position by
348	</p>
349
350	<ul>
351	<li>deliberately providing wrong information to users or developers</li>
352	<li>deliberately writing flawed documentation</li>
353	<li>deliberately corrupting documents</li>
354	<li>
355	deliberately go against the decisions made policy-wise or through a
356	consensus-model on the Gentoo Documentation mailinglist
357	</li>
358	<li>
359	not performing at all for a long time without informing the GDP and without
360	replying to the operational manager's request for a status update
361	</li>
362	</ul>
363
364	<p>
365	will be reported to the <uri link="/proj/en/devrel/">Gentoo Developer
366	Relations</uri> project.
367	</p>
368
369	</body>
370	</section>
371	</chapter>
372
373	<chapter>
374	<title>Documentation Team Recruitement</title>
375	<section>
376	<title>Contributors, Authors, Translators</title>
377	<body>
378
379	<p>
380	Everyone interested in contributing documentation, editing existing
381	documentation, writing new documentation or translating documentation is
382	welcome to join the team. There are no rules or strings attached to
383	this. Just make sure you are subscribed to <c>gentoo-doc@gentoo.org</c>
384	and you have fully read this policy and understand it.
385	</p>
386
387	</body>
388	</section>
389	<section>
390	<title>Recruitment Process</title>
391	<body>
392
393	<p>
394	The Documentation Project has a strict recruitment process outlined below.
395	This process can not be deviated from in any circumstance. We have opted for
396	this recruitment process to assure ourselves that the recruit is well informed
397	about the Gentoo Documentation Policy and the Gentoo Coding Style. It has proven
398	to be quite effective even though many contributors see it as a too large burden
399	to cross.
400	</p>
401
402	<p>
403	This recruitment process is meant only for requests to the Gentoo Documentation
404	Repository through CVS. Being listed as the maintainer or Point-Of-Contact for a
405	certain document or range of documents is granted by a simple request to the
406	Operational Manager or Project Lead.
407	</p>
408
409	</body>
410	</section>
411	<section>
412	<title>Phase 1: Contributions</title>
413	<body>
414
415	<p>
416	No recruitment process starts without investigating the contributions done
417	already to the Gentoo Documentation Project. The number of contributions must be
418	large to assure a good knowledge of GuideXML, Coding Style and policy. The
419	contribution period must be large as well to inform the contributor about the
420	time-consuming position and pressure the application involves.
421	</p>
422
423	<p>
424	The number of contributions and period over which the contributions should be
425	made depends on the position which the contributor solicits for. Although it is
426	difficult to write down these measurements in numbers, the following table
427	should give a general overview. Final decision however lays in the hands of the
428	Operational Manager.
429	</p>
430
431	<table>
432	<tr>
433	<th>Position</th>
434	<th>Minimal Activity</th>
435	<th>Minimal Period</th>
436	</tr>
437	<tr>
438	<ti>Full-time Developer</ti>
439	<ti>2 updates per week</ti>
440	<ti>1 month</ti>
441	</tr>
442	<tr>
443	<ti>Part-time Developer</ti>
444	<ti>4 updates per month</ti>
445	<ti>1 month</ti>
446	</tr>
447	</table>
448
449	<p>
450	An update constitutes a non-trivial update to any documentation, translation or
451	otherwise, completely written by the contributor and committed after review by
452	any existing documentation developer. The period is fixed - increasing the
453	contributions does not decrease the period. Also, we don't average the
454	contributions over time to make sure the contributor doesn't give a contribution
455	burst and then waits until the Phase is over.
456	</p>
457
458	<p>
459	Without this phase we can not know if the contributor understands what it takes
460	to be a documentation developer. The validation of this activity happens through
461	bugzilla reports.
462	</p>
463
464	<p>
465	Any request for CVS access that does not allow a development activity as written
466	down in the aforementioned table will not be taken into account.
467	</p>
468
469	<p>
470	If you feel that you have shown sufficient amount of contributions, contact
471	the Operational Manager of the Gentoo Documentation Project. He
472	will ask you for your coordinates and other information and then arrange
473	for the next phase to be started.
474	</p>
475
476	</body>
477	</section>
478	<section>
479	<title>Phase 2: Read-Only CVS Access</title>
480	<body>
481
482	<p>
483	During phase 2, the recruitee is given read-only access to the Gentoo
484	Documentation Repository, allowing him to generate commit-ready patches for the
485	tree. During this period, which is roughly the same as the aforementioned table,
486	his patches are not edited by a documentation developer anymore, but are either
487	committed as-is or refused. The recruit is also assigned to a full-time
488	documentation developer (the mentor) which will guide him through these last
489	phases.
490	</p>
491
492	<p>
493	The quality of the contributions are in this phase most important - every patch
494	that does not follow the Documentation Policy, Coding Style or other guideline
495	that affects the document is refused.
496	</p>
497
498	<p>
499	During this period, you:
500	</p>
501
502	<ul>
503	<li>
504	are advised to learn about Gentoo's inner workings.
505	This is required as you will be asked later on to answer Gentoo's <uri
506	link="/proj/en/devrel/quiz/staff-quiz.txt">Staffing Quiz</uri>.
507	</li>
508	<li>
509	will be asked to fill in the <uri
510	link="/proj/en/gdp/doc/doc-quiz.xml">Gentoo Documentation Project
511	Quiz</uri>. You need to successfully pass this entire quiz (all questions)
512	before you can continue with the next Phase.
513	</li>
514	</ul>
515
516	</body>
517	</section>
518	<section>
519	<title>Phase 3: Gentoo Recruitment</title>
520	<body>
521
522	<p>
523	When Phase 2 is finished, the Operational Manager will contact <uri
524	link="/proj/en/devrel">Developer Relations</uri> and give a final "Go!" for the
525	Gentoo recruitment process after which you will be given a Gentoo e-mail
526	address and be appointed to one or more subprojects.
527	</p>
528
529	</body>
530	</section>
531	</chapter>
532	</guide>