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