/[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.15 - (hide annotations) (download) (as text)
Thu Jun 2 16:58:03 2005 UTC (9 years, 5 months ago) by swift
Branch: MAIN
Changes since 1.14: +75 -66 lines
File MIME type: application/xml
Rewrite sentences in policy to make it more clear. Part of #94519

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

  ViewVC Help
Powered by ViewVC 1.1.20