/[gentoo]/xml/htdocs/proj/en/gdp/doc/doc-policy.xml
Gentoo

Diff of /xml/htdocs/proj/en/gdp/doc/doc-policy.xml

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

Revision 1.4 Revision 1.12
1<?xml version='1.0' encoding="UTF-8"?> 1<?xml version='1.0' encoding="UTF-8"?>
2<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/proj/en/gdp/doc/doc-policy.xml,v 1.4 2004/09/14 01:34:08 vapier Exp $ --> 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 3
4<!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> 4<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
5 5
6<guide link="/doc/en/doc-policy.xml"> 6<guide link="doc-policy.xml">
7 7
8<title>Gentoo Linux Documentation Policy</title> 8<title>Gentoo Linux Documentation Policy</title>
9<author title="Author"> 9<author title="Author">
10 <mail link="zhen@gentoo.org">John P. Davis</mail> 10 <mail link="zhen@gentoo.org">John P. Davis</mail>
11</author> 11</author>
25Contributers should know and exercise. 25Contributers should know and exercise.
26</abstract> 26</abstract>
27 27
28<license/> 28<license/>
29 29
30<version>3.6</version> 30<version>3.11</version>
31<date>August 14, 2004</date> 31<date>2005-05-07</date>
32 32
33<chapter> 33<chapter>
34<title>Introduction</title> 34<title>Introduction</title>
35<section> 35<section>
36<title>Introduction</title> 36<title>Introduction</title>
76represents an active development team of a Gentoo Documentation 76represents an active development team of a Gentoo Documentation
77Subproject. 77Subproject.
78</p> 78</p>
79 79
80<p> 80<p>
81The Gentoo Documentation Project is strategically lead by a top-level 81The Gentoo Documentation Project is strategically lead by a top-level manager
82manager as required by the 82as required by the <uri link="/doc/en/management-structure.xml">Gentoo
83<uri link="http://www.gentoo.org/doc/en/management-structure.xml">Gentoo
84Management Structure</uri>. This document also describes the responsibilities of 83Management Structure</uri>. This document also describes the responsibilities
85the strategic manager with respect to Gentoo Linux. 84of the strategic manager with respect to Gentoo Linux.
86</p> 85</p>
87 86
88<p> 87<p>
89For day-to-day managerial tasks the Gentoo Documentation Project has an 88For day-to-day managerial tasks the Gentoo Documentation Project has an
90operational manager. This person keeps track of all 89operational manager. This person keeps track of all documentation-related tasks
91documentation-related tasks that are more short-term. The operational 90that are more short-term. The operational manager and strategic manager can be
92manager and strategic manager can be one and the same if the strategic 91one and the same if the strategic manager wishes so.
93manager wishes so.
94</p> 92</p>
95 93
96<p> 94<p>
97Currently these positions are taken by the following people: 95Currently these positions are taken by the following people:
98</p> 96</p>
114 <ti><mail link="neysx@gentoo.org">neysx</mail></ti> 112 <ti><mail link="neysx@gentoo.org">neysx</mail></ti>
115</tr> 113</tr>
116</table> 114</table>
117 115
118<p> 116<p>
119Every subproject has a strategic manager of its own. he can 117Every subproject has a strategic manager of its own. he can have an operational
120have an operational manager if he deems appropriate. His 118manager if he deems appropriate. His responsibilities to the Gentoo
121responsibilities to the Gentoo Documentation Project are the same as are 119Documentation Project are the same as are listed on the <uri
122listed on the <uri
123link="http://www.gentoo.org/doc/en/management-structure.xml#doc_chap1_sect5">Gentoo 120link="/doc/en/management-structure.xml#doc_chap1_sect5">Gentoo Management
124Management Structure</uri>. 121Structure</uri>.
125</p>
126
127<p> 122</p>
123
124<p>
128The subprojects of the Gentoo Documentation Team together with their 125The subprojects of the Gentoo Documentation Team together with their respective
129respective strategic managers are listed on the <uri 126strategic managers are listed on the <uri link="/proj/en/gdp/">GDP
130link="http://www.gentoo.org/proj/en/gdp">GDP Website</uri>. 127Website</uri>.
131</p> 128</p>
132 129
133<p> 130<p>
134The decision on adding subprojects is in hands of the strategic manager. 131The decision on adding subprojects is in hands of the strategic manager.
135</p> 132</p>
147documentation-related issues. This mailing list is open to all interested 144documentation-related issues. This mailing list is open to all interested
148parties, developer or not. 145parties, developer or not.
149</p> 146</p>
150 147
151<p> 148<p>
152Every member of the Gentoo Documentation Project must be subscribed to 149Every member of the Gentoo Documentation Project must be part of the
153the <mail link="docs-team@gentoo.org">docs-team@gentoo.org</mail> alias. 150<mail link="docs-team@gentoo.org">docs-team@gentoo.org</mail> alias. This
154This alias is <e>only</e> used by <uri 151alias is <e>only</e> used by <uri
155link="http://bugs.gentoo.org">bugs.gentoo.org</uri> 152link="http://bugs.gentoo.org">bugs.gentoo.org</uri> to inform the documentation
156to inform the documentation team about bugs regarding the Gentoo 153team about bugs regarding the Gentoo Documentation. You can add yourself by
157Documentation. 154editing <path>/var/mail/alias/misc/docs-team</path> on dev.gentoo.org.
158</p> 155</p>
159 156
160<p> 157<p>
161Every member of the Gentoo Documentation Team should be available at 158Every member of the Gentoo Documentation Team should be available at
162<c>#gentoo-doc</c> on <uri link="http://www.freenode.net">irc.freenode.net</uri> 159<c>#gentoo-doc</c> on <uri link="http://www.freenode.net">irc.freenode.net</uri>
163whenever he is online. 160whenever he is online.
164</p> 161</p>
165 162
166<p> 163<p>
167Depending on his responsibilities, he can have limited CVS 164Depending on his responsibilities, he can have limited CVS
168access to <c>cvs.gentoo.org</c>. CVS access can only be given to Gentoo 165access to <c>cvs.gentoo.org</c>. Full CVS access can only be given to Gentoo
169developers. 166developers. Read-only CVS access can be given to recruitees.
170</p> 167</p>
171 168
172</body> 169</body>
173</section> 170</section>
174<section> 171<section>
239 236
240<p> 237<p>
241Every bug reported on <uri link="http://bugs.gentoo.org">bugs.gentoo.org</uri> 238Every bug reported on <uri link="http://bugs.gentoo.org">bugs.gentoo.org</uri>
242should be handled as fast as possible. If a bug cannot be handled 239should be handled as fast as possible. If a bug cannot be handled
243in a timely fashion, the reporter of that bug should be informed about 240in a timely fashion, the reporter of that bug should be informed about
244this using a comment on the bug. The tactical or operational manager can 241this using a comment on the bug and the bug should be registered in the
245decide that a bug has a higher priority and should be handled first before any 242<uri link="/proj/en/gdp/doc/metadoc-guide.xml">metadoc.xml</uri> file, if
246other task the assingee is responsible of. 243applicable. The tactical or operational manager can decide that a bug has a
244higher priority and should be handled first before any other task the assingee
245is responsible of.
247</p> 246</p>
248 247
249<p> 248<p>
250Whenever a Gentoo Documentation Team member takes care of a bug, he or 249Whenever a Gentoo Documentation Team member takes care of a bug, he or
251she should assign the bug to herself/himself, but make sure that 250she should assign the bug to herself/himself, but make sure that
259<section> 258<section>
260<title>Document Development</title> 259<title>Document Development</title>
261<body> 260<body>
262 261
263<p> 262<p>
264Every document the Gentoo Documentation Team develops can be developed 263Every document the Gentoo Documentation Team develops can be developed as the
265as the related parties see fit. However, when the document is finished, 264related parties see fit. However, when the document is finished, it should be
266it should be transformed into <uri 265transformed into <uri link="/doc/en/xml-guide.xml">GuideXML</uri> and put
267link="http://www.gentoo.org/doc/en/xml-guide.xml">GuideXML</uri>. 266available 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
268applicable.
268</p> 269</p>
269 270
270<p> 271<p>
271When a new document is started or a big change is needed, a bug should be filed 272When a new document is started or a big change is needed, a bug should be filed
272at <uri link="http://bugs.gentoo.org">bugs.gentoo.org</uri> 273at <uri link="http://bugs.gentoo.org">bugs.gentoo.org</uri>
283number (and date) increase. Note that the change of a Code Listings should 284number (and date) increase. Note that the change of a Code Listings should
284definitely cause an increase of the version number and date. 285definitely cause an increase of the version number and date.
285</p> 286</p>
286 287
287<p> 288<p>
288When updating a handbook-related file (such as the various
289<path>hb-*</path> files) you must bump the parental
290<path>handbook-&lt;arch&gt;.xml</path> file as well and commit all files at
291once (which also means an identical commit message).
292</p>
293
294<p>
295All changes in XML formatting should lead to version (and date) bumps only in 289All changes in XML formatting should lead to version (and date) bumps only in
296case the layout of the document changes. 290case the layout of the document changes.
297</p> 291</p>
298 292
299<p> 293<p>
328the CVS log to allow backtracing of changes. 322the CVS log to allow backtracing of changes.
329</p> 323</p>
330 324
331<p> 325<p>
332If a bugfix consists out of both content as internal coding changes, 326If a bugfix consists out of both content as internal coding changes,
333both changes must be committed seperately so that translators can easily 327both changes must be committed separately so that translators can easily
334view the important changes (content) and ignore the coding changes. 328view the important changes (content) and ignore the coding changes.
335</p> 329</p>
336 330
337<p> 331<p>
338In case of a translation, the lead translator of the language is 332In case of a translation, the lead translator of the language is
366 replying to the operational manager's request for a status update 360 replying to the operational manager's request for a status update
367 </li> 361 </li>
368</ul> 362</ul>
369 363
370<p> 364<p>
371will be reported to the <uri link="/proj/en/devrel">Gentoo Developer 365will be reported to the <uri link="/proj/en/devrel/">Gentoo Developer
372Relations</uri> project. 366Relations</uri> project.
373</p> 367</p>
374 368
375</body> 369</body>
376</section> 370</section>
391</p> 385</p>
392 386
393</body> 387</body>
394</section> 388</section>
395<section> 389<section>
396<title>Gentoo Documentation Developer</title> 390<title>Recruitment Process</title>
391<body>
392
393<p>
394The Documentation Project has a strict recruitment process outlined below.
395This process can not be deviated from in any circumstance. We have opted for
396this recruitment process to assure ourselves that the recruitee is well informed
397about the Gentoo Documentation Policy and the Gentoo Coding Style. It has proven
398to be quite effective even though many contributors see it as a too large burden
399to cross.
400</p>
401
402<p>
403This recruitment process is meant only for requests to the Gentoo Documentation
404Repository through CVS. Being listed as the maintainer or Point-Of-Contact for a
405certain document or range of documents is granted by a simple request to the
406Operational Manager or Project Lead.
407</p>
408
397<body> 409</body>
410</section>
411<section>
412<title>Phase 1: Contributions</title>
413<body>
398 414
399<p>
400As a Gentoo documentation developer should know everything in the <uri
401link="http://www.gentoo.org/doc/en/policy.xml">Gentoo Policy</uri>
402even though you're not submitting ebuilds. You should also have read the
403<uri link="http://www.gentoo.org/doc/en/gentoo-release-policy.xml">Gentoo
404Release Policy</uri> and <uri
405link="http://www.gentoo.org/doc/en/management-structure.xml">Gentoo Management
406Structure</uri>. This is all needed to ensure our userbase that no Gentoo
407developer gives wrong information about critical things.
408</p> 415<p>
409 416No recruitment process starts without investigating the contributions done
417already to the Gentoo Documentation Project. The number of contributions must be
418large to assure a good knowledge of GuideXML, Coding Style and policy. The
419contribution period must be large as well to inform the contributor about the
420time-consuming position and pressure the application involves.
410<p> 421</p>
422
423<p>
424The number of contributions and period over which the contributions should be
425made depends on the position which the contributor solicits for. Although it is
426difficult to write down these measurements in numbers, the following table
427should give a general overview. Final decision however lays in the hands of the
428Operational 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>
450An update constitutes a non-trivial update to any documentation, translation or
451otherwise, completely written by the contributor and committed after review by
452any existing documentation developer. The period is fixed - increasing the
453contributions does not decrease the period. Also, we don't average the
454contributions over time to make sure the contributor doesn't give a contribution
455burst and then waits until the Phase is over.
456</p>
457
458<p>
459Without this phase we can not know if the contributor understands what it takes
460to be a documentation developer. The validation of this activity happens through
461bugzilla reports.
462</p>
463
464<p>
465Any request for CVS access that does not allow a development activity as written
466down in the aforementioned table will not be taken into account.
467</p>
468
469<p>
470If you feel that you have shown sufficient amount of contributions, contact
411Contact the operational manager of the Gentoo Documentation Project. He 471the Operational Manager of the Gentoo Documentation Project. He
412will ask you for your coordinates and other information and then arrange 472will ask you for your coordinates and other information and then arrange
413a mentor for you who will guide you through the first days or weeks as 473for the next phase to be started.
414developer.
415</p>
416
417<p> 474</p>
418You will be given a Gentoo e-mail address and be appointed to one or
419more subprojects. During the initial days or weeks, you should ask your
420mentor as much as possible, preferably have him double-check everything
421you do. If your function requires CVS access, you will only receive it
422when your mentor deems it appropriate. Until then, your mentor is in
423charge of the CVS commits.
424</p>
425 475
426</body> 476</body>
427</section>
428<section> 477</section>
429<title>(Follow-Up) Lead Translator</title> 478<section>
479<title>Phase 2: Read-Only CVS Access</title>
480<body>
481
482<p>
483During phase 2, the recruitee is given read-only access to the Gentoo
484Documentation Repository, allowing him to generate commit-ready patches for the
485tree. During this period, which is roughly the same as the aforementioned table,
486his patches are not edited by a documentation developer anymore, but are either
487committed as-is or refused. The recruitee is also assigned to a full-time
488documentation developer (the mentor) which will guide him through these last
489phases.
490</p>
491
492<p>
493The quality of the contributions are in this phase most important - every patch
494that does not follow the Documentation Policy, Coding Style or other guideline
495that affects the document is refused.
496</p>
497
498<p>
499During 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 succesfully pass this entire quiz (all questions)
512 before you can continue with the next Phase.
513 </li>
514</ul>
515
430<body> 516</body>
517</section>
518<section>
519<title>Phase 3: Gentoo Recruitment</title>
520<body>
431 521
432<p>
433Becoming a (follow-up) lead translator shouldn't be held lightly. You are
434responsible for every translated document and final reviewing. The lead
435translator will make certain that the translated documents are
436grammatically and syntactically perfect.
437</p> 522<p>
438 523When Phase 2 is finished, the Operational Manager will contact <uri
439<p> 524link="/proj/en/devrel">Developer Relations</uri> and give a final "Go!" for the
440In order to become a Gentoo (follow-up) lead translator you must be a Gentoo 525Gentoo recruitment process after which you will be given a Gentoo e-mail
441developer. 526address and be appointed to one or more subprojects.
442</p>
443
444<p>
445During your "training" period you are a (follow-up) lead translator and
446should act upon it. All guidelines regarding (follow-up) lead translators
447apply.
448</p> 527</p>
449 528
450</body> 529</body>
451</section> 530</section>
452</chapter> 531</chapter>

Legend:
Removed from v.1.4  
changed lines
  Added in v.1.12

  ViewVC Help
Powered by ViewVC 1.1.20