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.20 2005/12/22 22:24:11 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="dberkholz@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.5 -->

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

<license/>

<version>3.17</version>
<date>2005-12-22</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 elsewhere.
</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 work in tandem 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 short-term tasks
related to documentation. 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 (GDP) are listed in the <e>Manager responsibilities</e>
section of the <uri
link="/doc/en/management-structure.xml#doc_chap1_sect5">Gentoo Management
Structure</uri> document.
</p>

<p>
Every subproject of the Gentoo Documentation Team is listed on the
<uri link="/proj/en/gdp/">GDP Webpage</uri>, along with their respective
Strategic Managers.
</p>

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

<p>
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. Read-only CVS access may be granted 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 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.
</p>

<p>
If a translated document for an unsupported language is contributed, the Gentoo
Documentation Team will not publish it officially. Such documents shall not be
linked to the website until an official Translation Team of that language is
formed.
</p>

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

<p>
For more information Gentoo document translations, please consult the
<uri link="/proj/en/gdp/doc/translators-howto.xml">
Translators Howto for Gentoo Documentation</uri> and the
<uri link="/proj/en/gdp/international.xml">
GDP Internationalisation Subproject</uri> page.
</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.5/">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.5 --&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 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.
</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. 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.
</p>

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

<p>
Every Gentoo Documentation Team may handle documentation development as it sees
fit. However, when the document is finished, it should be transformed into
<uri link="/doc/en/xml-guide.xml">GuideXML</uri> and made 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 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
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.
</p>

<p>
High-volume, technical or intrusive changes must be accompanied by a bug report
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 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.
</p>

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

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

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