/[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.4 - (hide annotations) (download) (as text)
Tue Sep 14 01:34:08 2004 UTC (10 years, 3 months ago) by vapier
Branch: MAIN
Changes since 1.3: +8 -8 lines
File MIME type: application/xml
the gender neutral pronoun in English is he, get over it

1 zhen 1.1 <?xml version='1.0' encoding="UTF-8"?>
2 vapier 1.4 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/proj/en/gdp/doc/doc-policy.xml,v 1.3 2004/08/26 16:16:04 swift Exp $ -->
3 swift 1.3
4 zhen 1.1 <!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
5    
6 swift 1.3 <guide link="/doc/en/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     <version>3.6</version>
31     <date>August 14, 2004</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     The Gentoo Documentation Project is strategically lead by a top-level
82     manager as required by the
83     <uri link="http://www.gentoo.org/doc/en/management-structure.xml">Gentoo
84     Management Structure</uri>. This document also describes the responsibilities of
85     the strategic manager with respect to Gentoo Linux.
86     </p>
87    
88     <p>
89     For day-to-day managerial tasks the Gentoo Documentation Project has an
90     operational manager. This person keeps track of all
91     documentation-related tasks that are more short-term. The operational
92     manager and strategic manager can be one and the same if the strategic
93     manager wishes so.
94     </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     <ti>Sven Vermeulen</ti>
109     <ti><mail link="swift@gentoo.org">swift</mail></ti>
110     </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     <p>
119 vapier 1.4 Every subproject has a strategic manager of its own. he can
120     have an operational manager if he deems appropriate. His
121 swift 1.3 responsibilities to the Gentoo Documentation Project are the same as are
122     listed on the <uri
123     link="http://www.gentoo.org/doc/en/management-structure.xml#doc_chap1_sect5">Gentoo
124     Management Structure</uri>.
125     </p>
126    
127     <p>
128     The subprojects of the Gentoo Documentation Team together with their
129     respective strategic managers are listed on the <uri
130     link="http://www.gentoo.org/proj/en/gdp">GDP Website</uri>.
131     </p>
132    
133     <p>
134     The decision on adding subprojects is in hands of the strategic manager.
135     </p>
136    
137     </body>
138     </section>
139     <section>
140     <title>Documentation Project Team Members</title>
141     <body>
142    
143     <p>
144     Every member of the Gentoo Documentation Project must be subscribed to
145     the <mail link="gentoo-doc-subscribe@gentoo.org">gentoo-doc@gentoo.org</mail>
146     mailing list. This mailing list will be used to discuss all
147     documentation-related issues. This mailing list is open to all interested
148     parties, developer or not.
149     </p>
150    
151     <p>
152     Every member of the Gentoo Documentation Project must be subscribed to
153     the <mail link="docs-team@gentoo.org">docs-team@gentoo.org</mail> alias.
154     This alias is <e>only</e> used by <uri
155     link="http://bugs.gentoo.org">bugs.gentoo.org</uri>
156     to inform the documentation team about bugs regarding the Gentoo
157     Documentation.
158     </p>
159    
160     <p>
161     Every member of the Gentoo Documentation Team should be available at
162     <c>#gentoo-doc</c> on <uri link="http://www.freenode.net">irc.freenode.net</uri>
163 vapier 1.4 whenever he is online.
164 swift 1.3 </p>
165    
166     <p>
167 vapier 1.4 Depending on his responsibilities, he can have limited CVS
168 swift 1.3 access to <c>cvs.gentoo.org</c>. CVS access can only be given to Gentoo
169     developers.
170     </p>
171    
172     </body>
173     </section>
174     <section>
175     <title>Documentation Translation Teams</title>
176     <body>
177    
178     <p>
179     Every language should be backed up by an official translation team. This
180     team is lead by a lead translator and perhaps a follow-up lead translator, who
181     both have CVS commit access. If for any reason the lead translator cannot
182     perform his or her duties, the follow-up lead translator is in charge. If
183     even this person is unavailable, the mentor(s) is/are in charge of the language.
184     </p>
185    
186     <p>
187     If a translated document is contributed, but the language in itself is
188     not supported, the Gentoo Documentation Team will not publish it
189     officially. In this case the document will stay unlinked until an official
190     translation team of that language is formed.
191     </p>
192    
193     <p>
194     When a language is officially supported, but the team doesn't have any
195     members or no one wants to take on the responsibilities of the lead
196     translator, all links to the documents will be removed from the site.
197     However, the documents will stay available in case the language becomes
198     officially supported again.
199     </p>
200 zhen 1.1
201 swift 1.3 </body>
202     </section>
203 zhen 1.1 </chapter>
204    
205 swift 1.3 <chapter>
206     <title>Gentoo Documentation Guidelines</title>
207     <section>
208     <title>Legal Issues</title>
209     <body>
210    
211     <p>
212     Every document published by the Gentoo Documentation Project must be
213     licensed by the <uri
214     link="http://creativecommons.org/licenses/by-sa/2.0/">Creative Commons
215     Attribution-ShareAlike License</uri>.
216     </p>
217    
218     <p>
219     Every document must have the following tag inside its GuideXML
220     sourcecode between the <c>&lt;/abstract&gt;</c> and the <c>&lt;version&gt;</c>
221     tags:
222     </p>
223    
224     <pre caption = "Licensing notice for the Gentoo Documentation">
225     &lt;/abstract&gt;
226     <i>
227     &lt;!-- The content of this document is licensed under the CC-BY-SA license --&gt;
228     &lt;!-- See http://creativecommons.org/licenses/by-sa/2.0 --&gt;
229     &lt;license/&gt;
230     </i>
231     &lt;version&gt;...&lt;/version&gt;
232     </pre>
233    
234     </body>
235     </section>
236     <section>
237     <title>Bugs and Updates</title>
238     <body>
239    
240     <p>
241     Every bug reported on <uri link="http://bugs.gentoo.org">bugs.gentoo.org</uri>
242     should be handled as fast as possible. If a bug cannot be handled
243     in a timely fashion, the reporter of that bug should be informed about
244     this using a comment on the bug. The tactical or operational manager can
245     decide that a bug has a higher priority and should be handled first before any
246     other task the assingee is responsible of.
247     </p>
248    
249     <p>
250     Whenever a Gentoo Documentation Team member takes care of a bug, he or
251     she should assign the bug to herself/himself, but make sure that
252     <c>docs-team@gentoo.org</c> is on the Cc-list. Unless with the consent
253     of the operational manager, a bug may not be taken away from another
254     Gentoo Documentation Team member without their approval.
255     </p>
256    
257     </body>
258     </section>
259     <section>
260     <title>Document Development</title>
261     <body>
262    
263     <p>
264     Every document the Gentoo Documentation Team develops can be developed
265     as the related parties see fit. However, when the document is finished,
266     it should be transformed into <uri
267     link="http://www.gentoo.org/doc/en/xml-guide.xml">GuideXML</uri>.
268     </p>
269    
270     <p>
271     When a new document is started or a big change is needed, a bug should be filed
272     at <uri link="http://bugs.gentoo.org">bugs.gentoo.org</uri>
273     concerning the development of this document. If there is already a bug
274     in the database that requests a change to the documentation, a new bug
275     does not have to be filed. Grammatical, syntactical or small changes
276     do not require a bug to be filed on <uri
277     link="http://bugs.gentoo.org">bugs.gentoo.org</uri> as well.
278     </p>
279    
280     <p>
281     All changes in contents of the document, except for typo fixes in text
282     itself or in the comments to code listings, should lead to version
283     number (and date) increase. Note that the change of a Code Listings should
284     definitely cause an increase of the version number and date.
285     </p>
286    
287     <p>
288     When updating a handbook-related file (such as the various
289     <path>hb-*</path> files) you must bump the parental
290     <path>handbook-&lt;arch&gt;.xml</path> file as well and commit all files at
291     once (which also means an identical commit message).
292     </p>
293    
294     <p>
295     All changes in XML formatting should lead to version (and date) bumps only in
296     case the layout of the document changes.
297     </p>
298    
299     <p>
300     Whether or not to increment the major version number instead of minor version
301     number or other is up to the editor.
302     </p>
303    
304     <p>
305     Every update of a translation should copy the new version information
306     verbatim from the master English document so fully synchronised
307     translations have the same version information.
308     </p>
309    
310     </body>
311     </section>
312     <section>
313     <title>Reviewing and Committing</title>
314     <body>
315    
316     <p>
317     To keep a high-pace development cycle of the documentation, technical or
318     intrusive changes to documents can be propagated immediately to the document
319     <e>if</e> the editor is 100% confident his changes are correct and working. If
320     you are not 100% confident (for instance because a user has told you how to fix
321     it but you cannot verify yourself), have the change reviewed by a Gentoo
322     Developer that can verify the change.
323     </p>
324    
325     <p>
326     High volume, technical or intrusive changes must be accompanied by a bugreport
327     on <uri>http://bugs.gentoo.org</uri>. This bugnumber <e>must</e> be mentioned in
328     the CVS log to allow backtracing of changes.
329     </p>
330    
331     <p>
332     If a bugfix consists out of both content as internal coding changes,
333     both changes must be committed seperately so that translators can easily
334     view the important changes (content) and ignore the coding changes.
335     </p>
336    
337     <p>
338     In case of a translation, the lead translator of the language is
339 vapier 1.4 responsible for the document. Only he may commit the document to CVS
340     unless he is currently "in training", in which case his or her
341 swift 1.3 mentor should commit it.
342     </p>
343    
344     </body>
345     </section>
346     <section>
347     <title>Sanctions</title>
348     <body>
349    
350     <p>
351     Although this has never been necessary, it is still important to list this in
352     the policy - even though it is hateful. Anyway, documentation developers that
353     misuse their position by
354     </p>
355    
356     <ul>
357     <li>deliberately providing wrong information to users or developers</li>
358     <li>deliberately writing flawed documentation</li>
359     <li>deliberately corrupting documents</li>
360     <li>
361     deliberately go against the decisions made policy-wise or through a
362     consensus-model on the Gentoo Documentation mailinglist
363     </li>
364     <li>
365     not performing at all for a long time without informing the GDP and without
366     replying to the operational manager's request for a status update
367     </li>
368     </ul>
369    
370     <p>
371     will be reported to the <uri link="/proj/en/devrel">Gentoo Developer
372     Relations</uri> project.
373     </p>
374 zhen 1.1
375 swift 1.3 </body>
376     </section>
377 zhen 1.1 </chapter>
378 swift 1.3
379 zhen 1.1 <chapter>
380 swift 1.3 <title>Documentation Team Recruitement</title>
381     <section>
382     <title>Contributors, Authors, Translators</title>
383     <body>
384    
385     <p>
386     Everyone interested in contributing documentation, editing existing
387     documentation, writing new documentation or translating documentation is
388     welcome to join the team. There are no rules or strings attached to
389     this. Just make sure you are subscribed to <c>gentoo-doc@gentoo.org</c>
390     and you have fully read this policy and understand it.
391     </p>
392    
393     </body>
394     </section>
395     <section>
396     <title>Gentoo Documentation Developer</title>
397     <body>
398    
399     <p>
400     As a Gentoo documentation developer should know everything in the <uri
401     link="http://www.gentoo.org/doc/en/policy.xml">Gentoo Policy</uri>
402     even though you're not submitting ebuilds. You should also have read the
403     <uri link="http://www.gentoo.org/doc/en/gentoo-release-policy.xml">Gentoo
404     Release Policy</uri> and <uri
405     link="http://www.gentoo.org/doc/en/management-structure.xml">Gentoo Management
406     Structure</uri>. This is all needed to ensure our userbase that no Gentoo
407     developer gives wrong information about critical things.
408     </p>
409    
410     <p>
411     Contact the operational manager of the Gentoo Documentation Project. He
412     will ask you for your coordinates and other information and then arrange
413     a mentor for you who will guide you through the first days or weeks as
414     developer.
415     </p>
416    
417     <p>
418     You will be given a Gentoo e-mail address and be appointed to one or
419     more subprojects. During the initial days or weeks, you should ask your
420 vapier 1.4 mentor as much as possible, preferably have him double-check everything
421 swift 1.3 you do. If your function requires CVS access, you will only receive it
422     when your mentor deems it appropriate. Until then, your mentor is in
423     charge of the CVS commits.
424     </p>
425    
426     </body>
427     </section>
428     <section>
429     <title>(Follow-Up) Lead Translator</title>
430     <body>
431    
432     <p>
433     Becoming a (follow-up) lead translator shouldn't be held lightly. You are
434     responsible for every translated document and final reviewing. The lead
435     translator will make certain that the translated documents are
436     grammatically and syntactically perfect.
437     </p>
438    
439     <p>
440     In order to become a Gentoo (follow-up) lead translator you must be a Gentoo
441     developer.
442     </p>
443    
444     <p>
445     During your "training" period you are a (follow-up) lead translator and
446     should act upon it. All guidelines regarding (follow-up) lead translators
447     apply.
448     </p>
449 zhen 1.1
450 swift 1.3 </body>
451     </section>
452 zhen 1.1 </chapter>
453     </guide>

  ViewVC Help
Powered by ViewVC 1.1.20