/[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.21 - (hide annotations) (download) (as text)
Sat Jul 8 17:21:18 2006 UTC (8 years ago) by neysx
Branch: MAIN
Changes since 1.20: +44 -44 lines
File MIME type: application/xml
s/spyderous/dberkholz/

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

  ViewVC Help
Powered by ViewVC 1.1.20