/[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.24 Revision 1.25
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.24 2010/11/08 22:54:00 nightmorph Exp $ --> 2<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/proj/en/gdp/doc/doc-policy.xml,v 1.25 2011/09/27 17:55:35 swift Exp $ -->
3<!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> 3<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
4 4
5<guide> 5<guide>
6<title>Gentoo Linux Documentation Policy</title> 6<title>Gentoo Linux Documentation Policy</title>
7 7
… …
24 24
25<!-- The content of this document is licensed under the CC-BY-SA license --> 25<!-- The content of this document is licensed under the CC-BY-SA license -->
26<!-- See http://creativecommons.org/licenses/by-sa/2.5 --> 26<!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
27<license/> 27<license/>
28 28
29<version>5</version> 29<version>6</version>
30<date>2010-11-08</date> 30<date>2011-09-23</date>
31 31
32<chapter> 32<chapter>
33<title>Introduction</title> 33<title>Introduction</title>
34<section> 34<section>
35<title>Introduction</title> 35<title>Introduction</title>
… …
37 37
38<p> 38<p>
39The Gentoo Linux Documentation team aspires to create exceptionally 39The Gentoo Linux Documentation team aspires to create exceptionally
40professional documentation that is immediately clear and concise to the 40professional documentation that is immediately clear and concise to the
41end user. In order to fulfill this goal, we have very specific rules and 41end user. In order to fulfill this goal, we have very specific rules and
42guidelines that <e>all</e> documentation must go through prior to 42guidelines that our documentation must go through prior to
43dissemination on our website, or elsewhere. 43dissemination on our website, or elsewhere.
44</p> 44</p>
45 45
46</body> 46</body>
47</section> 47</section>
… …
68<section> 68<section>
69<title>Organization</title> 69<title>Organization</title>
70<body> 70<body>
71 71
72<p> 72<p>
73The Gentoo Documentation Project Team is split into several smaller teams 73The Gentoo Documentation Project Team consists of editors and authors, working
74that work in tandem with each other. Each smaller team represents an active 74on our main documentation and its translations. Like most other Gentoo projects,
75development team of a Gentoo Documentation Subproject. 75it is lead by a project lead whose additional job is to look after the team and
76</p> 76its resources in general (such as focusing on recruitment when necessary and
77 77acting as an unbiased mediator when two or more developers have a dispute over
78<!-- 78something).
79<p> 79</p>
80The Gentoo Documentation Project is strategically led by a top-level Manager 80
81as required by the <uri link="/doc/en/management-structure.xml">Gentoo
82Management Structure</uri>. This document also describes the responsibilities
83of the Strategic Manager with respect to Gentoo Linux.
84</p> 81<p>
85--> 82When the Gentoo Documentation Team launches any subprojects, you will find its
86 83mission on our <uri link="/proj/en/gdp/">GDP Project Webpage</uri>, along with
87<p> 84their respective project leads.
88For day-to-day managerial tasks, the Gentoo Documentation Project has an
89Operational Manager. This person keeps track of all short-term tasks
90related to documentation. The Operational Manager and Strategic Manager can be
91one and the same if the Strategic Manager wishes so.
92</p>
93
94<p>
95Currently 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>Joshua Saddler</ti>
107 <ti><mail link="nightmorph@gentoo.org">nightmorph</mail></ti>
108</tr>
109<tr>
110 <ti>Operational Manager</ti>
111 <ti>Joshua Saddler</ti>
112 <ti><mail link="nightmorph@gentoo.org">nightmorph</mail></ti>
113</tr>
114</table>
115
116<!--
117<p>
118Every subproject has a Strategic Manager of its own, and may have an
119Operational Manager if deemed appropriate. His responsibilities to the Gentoo
120Documentation Project (GDP) are listed in the <e>Manager responsibilities</e>
121section of the <uri
122link="/doc/en/management-structure.xml#doc_chap1_sect5">Gentoo Management
123Structure</uri> document.
124</p>
125-->
126
127<p>
128Every subproject of the Gentoo Documentation Team is listed on the
129<uri link="/proj/en/gdp/">GDP Webpage</uri>, along with their respective
130Strategic Managers.
131</p>
132
133<p>
134The decision on adding a subproject is in the hands of the Strategic Manager.
135</p> 85</p>
136 86
137</body> 87</body>
138</section> 88</section>
139<section> 89<section>
… …
151<p> 101<p>
152Every member of the Gentoo Documentation Project must be part of the 102Every member of the Gentoo Documentation Project must be part of the
153<mail>docs-team@gentoo.org</mail> alias. This alias is <e>only</e> used by <uri 103<mail>docs-team@gentoo.org</mail> alias. This alias is <e>only</e> used by <uri
154link="http://bugs.gentoo.org">bugs.gentoo.org</uri> to inform the documentation 104link="http://bugs.gentoo.org">bugs.gentoo.org</uri> to inform the documentation
155team about bugs regarding the Gentoo Documentation. You can add yourself by 105team about bugs regarding the Gentoo Documentation. You can add yourself by
156editing <path>/var/mail/alias/misc/docs-team</path> on dev.gentoo.org. 106editing <path>/var/mail/alias/misc/docs-team</path> on dev.gentoo.org. Please do
157</p> 107<e>not</e> use this address to try and contact the team - you can contact us
158 108through the mailinglist, IRC or by mailing the project lead or any other member.
159<p> 109</p>
160Members of the Gentoo Documentation Team should be available at 110
111<p>
112Members of the Gentoo Documentation Team are frequently online in
161<c>#gentoo-doc</c> on <uri link="http://www.freenode.net">irc.freenode.net</uri> 113<c>#gentoo-doc</c> on <uri link="http://www.freenode.net">irc.freenode.net</uri>.
162whenever they are online.
163</p>
164
165<p> 114</p>
115
116<p>
166Depending on the assignment or responsibilities, a member may have limited CVS 117Depending on the assignment or responsibilities, a member may have CVS
167access to <c>cvs.gentoo.org</c>. Full CVS access is restricted to Gentoo 118access to <c>cvs.gentoo.org</c>. Interested non-developers can use the
168Developers. An <uri link="http://anoncvs.gentoo.org">anonymous CVS server</uri> 119<uri link="http://anoncvs.gentoo.org">anonymous CVS server</uri>
169is available. It contains the same files as our CVS server but is a few minutes 120to help out with the documentation. It contains the same files as our CVS
170late. 121server but is a few minutes late.
171</p> 122</p>
172 123
173</body> 124</body>
174</section> 125</section>
175<section> 126<section>
… …
177<body> 128<body>
178 129
179<p> 130<p>
180Every language should be backed up by an official Translation Team. This 131Every language should be backed up by an official Translation Team. This
181team is led by a <e>Lead Translator</e> and perhaps a <e>Follow-On Lead 132team is led by a <e>Lead Translator</e> and perhaps a <e>Follow-On Lead
182Translator</e>, who both have CVS commit access. If for any reason the 133Translator</e>, who both have CVS commit access. Organization of the
183<e>Lead Translator</e> cannot perform his duties, the <e>Follow-On Lead 134translations is handled by the lead translator as he or she sees fit, as
184Translator</e> is in charge. If the <e>Follow-On</e> is unavailable, the 135long as the committed translations follow this policy.
185mentor(s) is/are in charge of the language.
186</p> 136</p>
187 137
188<p> 138<p>
189If a translated document for an unsupported language is contributed, the Gentoo 139If a translated document for an unsupported language is contributed, the Gentoo
190Documentation Team will publish it as-is. Such documents will not be linked to 140Documentation Team will publish it as-is. Such documents will not be linked to
191the website until an official Translation Team of that language is formed, but 141the website until an official Translation Team of that language is formed, but
192they will be available on our site and in CVS. 142they will be available on our site and in CVS.
193</p>
194
195<p>
196When a language is officially supported, but the team does not have any
197members willing to take on the responsibilities of the <e>Lead
198Translator</e>, all links to the documents will be removed from the site.
199However, the documents will stay available in case the language becomes
200officially supported again.
201</p> 143</p>
202 144
203<p> 145<p>
204For more information Gentoo document translations, please consult the 146For more information Gentoo document translations, please consult the
205<uri link="/proj/en/gdp/doc/translators-howto.xml"> 147<uri link="/proj/en/gdp/doc/translators-howto.xml">
… …
251Every bug reported on <uri link="http://bugs.gentoo.org">bugs.gentoo.org</uri> 193Every bug reported on <uri link="http://bugs.gentoo.org">bugs.gentoo.org</uri>
252should be handled as fast as possible. If a bug cannot be handled 194should be handled as fast as possible. If a bug cannot be handled
253in a timely fashion, the reporter of that bug should be informed about 195in a timely fashion, the reporter of that bug should be informed about
254this using a comment on the bug, and the bug should be registered in the 196this using a comment on the bug, and the bug should be registered in the
255<uri link="/proj/en/gdp/doc/metadoc-guide.xml">metadoc.xml</uri> file, if 197<uri link="/proj/en/gdp/doc/metadoc-guide.xml">metadoc.xml</uri> file, if
256applicable. The Strategic or Operational Manager may decide that a bug has a 198applicable.
257higher priority and should be addressed ahead any other task the assignee
258is responsible for.
259</p> 199</p>
260 200
261<p> 201<p>
262Whenever a Gentoo Documentation Team member takes care of a bug, he or she 202Whenever a Gentoo Documentation Team member takes care of a bug, he or she
263should assign the bug to herself/himself, but make sure that 203should assign the bug to herself/himself, but make sure that
264<mail>docs-team@gentoo.org</mail> is on the Cc-list. A bug may not be taken 204<mail>docs-team@gentoo.org</mail> is on the Cc-list. A bug may not be taken
265away from another Gentoo Documentation Team member without their approval; 205away from another Gentoo Documentation Team member without their approval
266unless consent has been received from the Operational Manager. 206unless consent has been received from the project lead.
267</p> 207</p>
268 208
269</body> 209</body>
270</section> 210</section>
271<section> 211<section>
… …
302All changes in XML formatting should lead to version and date bumps only in 242All changes in XML formatting should lead to version and date bumps only in
303case the layout of the HTML document changes. 243case the layout of the HTML document changes.
304</p> 244</p>
305 245
306<p> 246<p>
307Whether or not to increment the major version number instead of minor version 247Versions should always be handled as integers, so a version bump of version
308number or other is up to the editor. 248<c>2</c> leads to version <c>3</c>. Historical versions that use the major and
249minor syntax should be converted to the next integer on the next update, so
250version <c>3.2</c> becomes version <c>4</c>.
309</p> 251</p>
310 252
311<p> 253<p>
312Every update of a translation should use the version and date information 254Every update of a translation should use the version and date information
313verbatim from the master English document so fully synchronised translations 255verbatim from the master English document so fully synchronised translations
… …
322 264
323<p> 265<p>
324To maintain a high-paced documentation development cycle, technical or 266To maintain a high-paced documentation development cycle, technical or
325intrusive changes to documents can be propagated immediately to the document. 267intrusive changes to documents can be propagated immediately to the document.
326This is allowed only <e>if</e> the editor is absolutely confident the changes 268This is allowed only <e>if</e> the editor is absolutely confident the changes
327are functional. If you are not absolutely confident (for instance because a 269are functionally correct. If you are not absolutely confident (for instance because a
328user has told you how to fix it but you cannot verify yourself), have the 270user has told you how to fix it but you cannot verify yourself), have the
329changes reviewed by a Gentoo Developer that can verify the changes are apt. 271changes reviewed by a third person that can verify the changes are apt.
330</p> 272</p>
331 273
332<p> 274<p>
333High-volume, technical or intrusive changes must be accompanied by a bug report 275High-volume, technical or intrusive changes must be accompanied by a bug report
334on <uri>http://bugs.gentoo.org</uri>. This bug number <e>must</e> be mentioned 276on <uri>http://bugs.gentoo.org</uri>. This bug number <e>must</e> be mentioned
… …
339If a bugfix includes changes to content as well as internal coding changes, 281If a bugfix includes changes to content as well as internal coding changes,
340both changes must be committed separately. This allows translators to focus 282both changes must be committed separately. This allows translators to focus
341on the relevant changes regarding content and ignore the coding changes. 283on the relevant changes regarding content and ignore the coding changes.
342</p> 284</p>
343 285
344<p>
345If the document in question is a translation, the <e>Lead Translator</e> of the
346affected language is responsible for the document. Only the <e>Lead
347Translator</e> and his follow-on may commit the document to the CVS repository.
348However, if the <e>Lead Translator</e> is currently "in training", the
349trainee's mentor should commit the changes.
350</p>
351
352</body> 286</body>
353</section> 287</section>
354<section> 288<section>
355<title>Sanctions</title> 289<title>Sanctions</title>
356<body> 290<body>
357 291
358<p> 292<p>
359Malicious conduct by developers has never been an issue. However, it should be 293Malicious conduct by developers has not been an issue before. However, it
360noted that documentation developers that misuse their position by 294should be noted that documentation developers that misuse their position by
361</p> 295</p>
362 296
363<ul> 297<ul>
364 <li>deliberately providing wrong information to users or developers</li> 298 <li>deliberately providing wrong information to users or developers</li>
365 <li>deliberately writing flawed documentation</li> 299 <li>deliberately writing flawed documentation</li>
366 <li>deliberately corrupting documents</li> 300 <li>deliberately corrupting documents</li>
367 <li> 301 <li>
368 deliberately go against the decisions made policy-wise or through a 302 deliberately go against the decisions made policy-wise or through a
369 consensus-model on the Gentoo Documentation mailinglist 303 consensus-model on the Gentoo Documentation mailinglist
370 </li> 304 </li>
371 <li>
372 not performing at all for a long time without informing the GDP, and without 305 <li>not performing at all for a long time without informing the GDP</li>
373 replying to the Operational Manager's request for a status update
374 </li>
375</ul> 306</ul>
376 307
377<p> 308<p>
378will be reported to the <uri link="/proj/en/devrel/">Gentoo Developer 309will be reported to the <uri link="/proj/en/devrel/">Gentoo Developer
379Relations</uri> project. 310Relations</uri> project.
… …
402<section> 333<section>
403<title>Recruitment Process</title> 334<title>Recruitment Process</title>
404<body> 335<body>
405 336
406<p> 337<p>
407The Documentation Project has a strict recruitment process outlined below. 338The Documentation Project uses the recruitment process outlined below.
408This process can not be deviated from in any circumstance. We have opted for
409this recruitment process to assure ourselves that the recruit is well informed 339We have opted for this recruitment process to assure ourselves that the recruit
410about the Gentoo Documentation Policy and the Gentoo Coding Style. It has proven 340is well informed about the Gentoo Documentation Policy and the Gentoo Coding
411to be quite effective even though many contributors see it as a too large burden 341Style. It has proven to be quite effective even though many contributors see it
412to cross. 342as a too large burden to cross.
413</p> 343</p>
414 344
415<p> 345<p>
416This recruitment process is meant only for requests to the Gentoo Documentation 346This recruitment process is meant only for requests to the Gentoo Documentation
417Repository through CVS. Being listed as the maintainer or point of contact for 347Repository through CVS. Being listed as the maintainer or point of contact for
418a certain document or range of documents is granted by a simple request to the 348a certain document or range of documents does not require developer access.
419Operational Manager or Project Lead.
420</p> 349</p>
421 350
422</body> 351</body>
423</section> 352</section>
424<section> 353<section>
… …
427 356
428<p> 357<p>
429No recruitment process starts without investigating the contributions done 358No recruitment process starts without investigating the contributions done
430already to the Gentoo Documentation Project. The number of contributions must be 359already to the Gentoo Documentation Project. The number of contributions must be
431large to assure a good knowledge of GuideXML, Coding Style and policy. The 360large to assure a good knowledge of GuideXML, Coding Style and policy. The
432contribution period must be large as well to inform the contributor about the 361contribution period must be large as well to allow the contributor to find out
433time-consuming position and pressure the application involves. 362if he can provide continuous support for the Gentoo Documentation Project.
434</p>
435
436<p> 363</p>
437The number of contributions and period over which the contributions should be
438made depends on the position which the contributor solicits for. Although it is
439difficult to write down these measurements in numbers, the following table
440should give a general overview. Final decision however lays in the hands of the
441Operational Manager.
442</p>
443
444<table>
445<tr>
446 <th>Position</th>
447 <th>Minimal Activity</th>
448 <th>Minimal Period</th>
449</tr>
450<tr>
451 <ti>Full-time Developer</ti>
452 <ti>2 updates per week</ti>
453 <ti>1 month</ti>
454</tr>
455<tr>
456 <ti>Part-time Developer</ti>
457 <ti>4 updates per month</ti>
458 <ti>1 month</ti>
459</tr>
460</table>
461 364
462<p> 365<p>
463An update constitutes a non-trivial update to any documentation, translation or 366An update constitutes a non-trivial update to any documentation, translation or
464otherwise, completely written by the contributor and committed after review by 367otherwise, completely written or edited by the contributor and committed after
465any existing documentation developer. The period is fixed - increasing the 368review by any existing documentation developer.
466contributions does not decrease the period. Also, we don't average the
467contributions over time to make sure the contributor doesn't give a contribution
468burst, and then waits until the phase is over.
469</p>
470
471<p>
472Without this phase, we can not know if the contributor understands what it
473takes to be a documentation developer. The validation of this activity happens
474through bugzilla reports.
475</p>
476
477<p>
478Any request for CVS access that does not allow a development activity as written
479down in the aforementioned table will not be taken into account.
480</p> 369</p>
481 370
482<p> 371<p>
483If you feel that you have shown sufficient amount of contributions, contact 372If you feel that you have shown sufficient amount of contributions, contact
484the Operational Manager of the Gentoo Documentation Project. He 373the project lead of the Gentoo Documentation Project. He will ask you for your
485will ask you for your coordinates and other information, and then arrange 374coordinates and other information, and then arrange for the next phase to be
486for the next phase to be started. 375started.
487</p> 376</p>
488 377
489</body> 378</body>
490</section> 379</section>
491<section> 380<section>
492<title>Phase 2: Start the Recruitment Process</title> 381<title>Phase 2: Start the Recruitment Process</title>
493<body> 382<body>
494 383
495<p> 384<p>
496During this period, which is roughly the same as the aforementioned table, 385During this period, submitted patches are not edited by a documentation
497submitted patches are not edited by a documentation developer anymore, but are 386developer anymore, but are either committed as-is or refused. The recruit is
498either committed as-is or refused. The recruit is also assigned to a full-time
499documentation developer (the mentor) which will guide him through these last 387also assigned to a documentation developer (the mentor) which will guide him
500phases. 388through these last phases.
501</p> 389</p>
502 390
503<p> 391<p>
504The quality of the contributions are in this phase most important - every patch 392The quality of the contributions are in this phase most important - every patch
505that does not follow the Documentation Policy, Coding Style or other guideline 393that does not follow the Documentation Policy, Coding Style or other guideline
506that affects the document is refused. 394that affects the document is tackled by the recruit himself with help of the
507</p> 395mentor.
508
509<p> 396</p>
397
398<p>
510During this period, you: 399During this period, the recruit:
511</p> 400</p>
512 401
513<ul> 402<ul>
514 <li> 403 <li>
515 are advised to learn about Gentoo's inner workings. 404 is advised to learn about Gentoo's inner workings.
516 This is required as you will be asked later on to answer Gentoo's <uri 405 This is required as he or she will be asked later on to answer Gentoo's <uri
517 link="/proj/en/devrel/quiz/staff-quiz.txt">Staffing Quiz</uri>. 406 link="/proj/en/devrel/quiz/staff-quiz.txt">Staffing Quiz</uri>.
518 </li> 407 </li>
519 <li> 408 <li>
520 will be asked to fill in the <uri 409 will be asked to fill in the <uri
521 link="/proj/en/gdp/doc/doc-quiz.xml">Gentoo Documentation Project 410 link="/proj/en/gdp/doc/doc-quiz.xml">Gentoo Documentation Project
522 Quiz</uri>. You need to successfully pass this entire quiz (all questions) 411 Quiz</uri>. He or she needs to successfully pass this entire quiz
523 before you can continue with the next Phase. 412 (all questions) before we can continue with the next Phase.
524 </li> 413 </li>
525</ul> 414</ul>
526 415
527</body> 416</body>
528</section> 417</section>
529<section> 418<section>
530<title>Phase 3: Gentoo Recruitment</title> 419<title>Phase 3: Gentoo Recruitment</title>
531<body> 420<body>
532 421
533<p> 422<p>
534When Phase 2 is finished, the Operational Manager will contact <uri 423When Phase 2 is finished, the project lead will contact <uri
535link="/proj/en/devrel/">Developer Relations</uri> and give a final "Go!" for the 424link="/proj/en/devrel/">Developer Relations</uri> and give a final "Go!" for the
536Gentoo recruitment process after which you will be given a Gentoo e-mail 425Gentoo recruitment process after which the recruit will be given access to the
537address and be appointed to one or more subprojects. 426necessary Gentoo infrastructural services (like the documentation repository).
427</p>
428
429</body>
430</section>
431<section>
432<title>Recruitment of Existing Gentoo Developers</title>
433<body>
434
435<p>
436If the recruit is already a Gentoo Developer, the same recruitment process is
437followed, but the staffing quiz is not necessary anymore. However, the <uri
438link="/proj/en/gdp/doc/doc-quiz.xml">Gentoo Documentation Project Quiz</uri> is
439still mandatory.
538</p> 440</p>
539 441
540</body> 442</body>
541</section> 443</section>
542</chapter> 444</chapter>
Legend:
Removed from v.1.24  
changed lines
  Added in v.1.25
  ViewVC Help
Powered by ViewVC 1.1.13