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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.24 - (hide annotations) (download) (as text)
Mon Nov 8 22:54:00 2010 UTC (3 years, 11 months ago) by nightmorph
Branch: MAIN
Changes since 1.23: +10 -12 lines
File MIME type: application/xml
Xavier (neysx) has been retired. I'm taking over as GDP lead. Documentation updated accordingly.

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

  ViewVC Help
Powered by ViewVC 1.1.20