/[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.11 - (hide annotations) (download) (as text)
Sat May 7 19:06:52 2005 UTC (9 years, 7 months ago) by swift
Branch: MAIN
Changes since 1.10: +122 -33 lines
File MIME type: application/xml
Update on GDP policy

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

  ViewVC Help
Powered by ViewVC 1.1.20