/[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.18 - (hide annotations) (download) (as text)
Sat Nov 26 13:09:02 2005 UTC (8 years, 9 months ago) by jkt
Branch: MAIN
Changes since 1.17: +2 -3 lines
File MIME type: application/xml
Sorry for broken ChangeLog of last commit - tt should have been
"bumping CC-BY-SA to 2.5", *not* "adding CVS $Header$".
Bumping <version> once again to make sure everyone will catch it :-(.

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

  ViewVC Help
Powered by ViewVC 1.1.20