/[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.23 - (hide annotations) (download) (as text)
Mon Mar 5 12:57:48 2007 UTC (8 years, 1 month ago) by neysx
Branch: MAIN
Changes since 1.22: +49 -49 lines
File MIME type: application/xml
Spring refresh

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

  ViewVC Help
Powered by ViewVC 1.1.20