/[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.8 - (hide annotations) (download) (as text)
Tue Dec 28 17:20:15 2004 UTC (9 years, 11 months ago) by swift
Branch: MAIN
Changes since 1.7: +12 -7 lines
File MIME type: application/xml
Add metadoc.xml file usage

1 zhen 1.1 <?xml version='1.0' encoding="UTF-8"?>
2 swift 1.8 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/proj/en/gdp/doc/doc-policy.xml,v 1.7 2004/11/09 08:35:47 swift 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.8 <version>3.9</version>
31     <date>2004-12-28</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 swift 1.8 this using a comment on the bug and the bug should be registered in the
245     <uri link="/proj/en/gdp/doc/metadoc-guide.xml">metadoc.xml</uri> file, if
246     applicable. The tactical or operational manager can decide that a bug has a
247     higher priority and should be handled first before any other task the assingee
248     is responsible of.
249 swift 1.3 </p>
250    
251     <p>
252     Whenever a Gentoo Documentation Team member takes care of a bug, he or
253     she should assign the bug to herself/himself, but make sure that
254     <c>docs-team@gentoo.org</c> is on the Cc-list. Unless with the consent
255     of the operational manager, a bug may not be taken away from another
256     Gentoo Documentation Team member without their approval.
257     </p>
258    
259     </body>
260     </section>
261     <section>
262     <title>Document Development</title>
263     <body>
264    
265     <p>
266     Every document the Gentoo Documentation Team develops can be developed
267     as the related parties see fit. However, when the document is finished,
268     it should be transformed into <uri
269 swift 1.8 link="http://www.gentoo.org/doc/en/xml-guide.xml">GuideXML</uri> and put
270     available on the Gentoo CVS infrastructure. It must also be registered in the
271     <uri link="/proj/en/gdp/doc/metadoc-guide.xml">metadoc.xml</uri> file if
272     applicable.
273 swift 1.3 </p>
274    
275     <p>
276     When a new document is started or a big change is needed, a bug should be filed
277     at <uri link="http://bugs.gentoo.org">bugs.gentoo.org</uri>
278     concerning the development of this document. If there is already a bug
279     in the database that requests a change to the documentation, a new bug
280     does not have to be filed. Grammatical, syntactical or small changes
281     do not require a bug to be filed on <uri
282     link="http://bugs.gentoo.org">bugs.gentoo.org</uri> as well.
283     </p>
284    
285     <p>
286     All changes in contents of the document, except for typo fixes in text
287     itself or in the comments to code listings, should lead to version
288     number (and date) increase. Note that the change of a Code Listings should
289     definitely cause an increase of the version number and date.
290     </p>
291    
292     <p>
293     When updating a handbook-related file (such as the various
294     <path>hb-*</path> files) you must bump the parental
295     <path>handbook-&lt;arch&gt;.xml</path> file as well and commit all files at
296     once (which also means an identical commit message).
297     </p>
298    
299     <p>
300     All changes in XML formatting should lead to version (and date) bumps only in
301     case the layout of the document changes.
302     </p>
303    
304     <p>
305     Whether or not to increment the major version number instead of minor version
306     number or other is up to the editor.
307     </p>
308    
309     <p>
310     Every update of a translation should copy the new version information
311     verbatim from the master English document so fully synchronised
312     translations have the same version information.
313     </p>
314    
315     </body>
316     </section>
317     <section>
318     <title>Reviewing and Committing</title>
319     <body>
320    
321     <p>
322     To keep a high-pace development cycle of the documentation, technical or
323     intrusive changes to documents can be propagated immediately to the document
324     <e>if</e> the editor is 100% confident his changes are correct and working. If
325     you are not 100% confident (for instance because a user has told you how to fix
326     it but you cannot verify yourself), have the change reviewed by a Gentoo
327     Developer that can verify the change.
328     </p>
329    
330     <p>
331     High volume, technical or intrusive changes must be accompanied by a bugreport
332     on <uri>http://bugs.gentoo.org</uri>. This bugnumber <e>must</e> be mentioned in
333     the CVS log to allow backtracing of changes.
334     </p>
335    
336     <p>
337     If a bugfix consists out of both content as internal coding changes,
338     both changes must be committed seperately so that translators can easily
339     view the important changes (content) and ignore the coding changes.
340     </p>
341    
342     <p>
343     In case of a translation, the lead translator of the language is
344 vapier 1.4 responsible for the document. Only he may commit the document to CVS
345     unless he is currently "in training", in which case his or her
346 swift 1.3 mentor should commit it.
347     </p>
348    
349     </body>
350     </section>
351     <section>
352     <title>Sanctions</title>
353     <body>
354    
355     <p>
356     Although this has never been necessary, it is still important to list this in
357     the policy - even though it is hateful. Anyway, documentation developers that
358     misuse their position by
359     </p>
360    
361     <ul>
362     <li>deliberately providing wrong information to users or developers</li>
363     <li>deliberately writing flawed documentation</li>
364     <li>deliberately corrupting documents</li>
365     <li>
366     deliberately go against the decisions made policy-wise or through a
367     consensus-model on the Gentoo Documentation mailinglist
368     </li>
369     <li>
370     not performing at all for a long time without informing the GDP and without
371     replying to the operational manager's request for a status update
372     </li>
373     </ul>
374    
375     <p>
376     will be reported to the <uri link="/proj/en/devrel">Gentoo Developer
377     Relations</uri> project.
378     </p>
379 zhen 1.1
380 swift 1.3 </body>
381     </section>
382 zhen 1.1 </chapter>
383 swift 1.3
384 zhen 1.1 <chapter>
385 swift 1.3 <title>Documentation Team Recruitement</title>
386     <section>
387     <title>Contributors, Authors, Translators</title>
388     <body>
389    
390     <p>
391     Everyone interested in contributing documentation, editing existing
392     documentation, writing new documentation or translating documentation is
393     welcome to join the team. There are no rules or strings attached to
394     this. Just make sure you are subscribed to <c>gentoo-doc@gentoo.org</c>
395     and you have fully read this policy and understand it.
396     </p>
397    
398     </body>
399     </section>
400     <section>
401     <title>Gentoo Documentation Developer</title>
402     <body>
403    
404     <p>
405     As a Gentoo documentation developer should know everything in the <uri
406 swift 1.6 link="/proj/en/devrel/handbook/handbook.xml?part=3&amp;chap=1">Gentoo Ebuild
407 swift 1.7 Policy</uri> even though you're not submitting ebuilds. This is all needed to
408     ensure our userbase that no Gentoo developer gives wrong information about
409     critical things.
410 swift 1.3 </p>
411    
412     <p>
413     Contact the operational manager of the Gentoo Documentation Project. He
414     will ask you for your coordinates and other information and then arrange
415     a mentor for you who will guide you through the first days or weeks as
416     developer.
417     </p>
418    
419     <p>
420     You will be given a Gentoo e-mail address and be appointed to one or
421     more subprojects. During the initial days or weeks, you should ask your
422 vapier 1.4 mentor as much as possible, preferably have him double-check everything
423 swift 1.3 you do. If your function requires CVS access, you will only receive it
424     when your mentor deems it appropriate. Until then, your mentor is in
425     charge of the CVS commits.
426     </p>
427    
428     </body>
429     </section>
430     <section>
431     <title>(Follow-Up) Lead Translator</title>
432     <body>
433    
434     <p>
435     Becoming a (follow-up) lead translator shouldn't be held lightly. You are
436     responsible for every translated document and final reviewing. The lead
437     translator will make certain that the translated documents are
438     grammatically and syntactically perfect.
439     </p>
440    
441     <p>
442     In order to become a Gentoo (follow-up) lead translator you must be a Gentoo
443     developer.
444     </p>
445    
446     <p>
447     During your "training" period you are a (follow-up) lead translator and
448     should act upon it. All guidelines regarding (follow-up) lead translators
449     apply.
450     </p>
451 zhen 1.1
452 swift 1.3 </body>
453     </section>
454 zhen 1.1 </chapter>
455     </guide>

  ViewVC Help
Powered by ViewVC 1.1.20