/[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.9 - (hide annotations) (download) (as text)
Fri Jan 7 23:02:29 2005 UTC (9 years, 6 months ago) by neysx
Branch: MAIN
Changes since 1.8: +27 -39 lines
File MIME type: application/xml
Content change: date/version bumping of master handbook file is not required anymore whenever a part is updated.
Cosmetic changes: links/coding style

1 zhen 1.1 <?xml version='1.0' encoding="UTF-8"?>
2 neysx 1.9 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/proj/en/gdp/doc/doc-policy.xml,v 1.8 2004/12/28 17:20:15 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 neysx 1.9 <version>3.10</version>
31     <date>2005-01-08</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 neysx 1.9 Every member of the Gentoo Documentation Project must be subscribed to the
150     <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     team about bugs regarding the Gentoo Documentation.
154 swift 1.3 </p>
155    
156     <p>
157     Every member of the Gentoo Documentation Team should be available at
158     <c>#gentoo-doc</c> on <uri link="http://www.freenode.net">irc.freenode.net</uri>
159 vapier 1.4 whenever he is online.
160 swift 1.3 </p>
161    
162     <p>
163 vapier 1.4 Depending on his responsibilities, he can have limited CVS
164 swift 1.3 access to <c>cvs.gentoo.org</c>. CVS access can only be given to Gentoo
165     developers.
166     </p>
167    
168     </body>
169     </section>
170     <section>
171     <title>Documentation Translation Teams</title>
172     <body>
173    
174     <p>
175     Every language should be backed up by an official translation team. This
176     team is lead by a lead translator and perhaps a follow-up lead translator, who
177     both have CVS commit access. If for any reason the lead translator cannot
178     perform his or her duties, the follow-up lead translator is in charge. If
179     even this person is unavailable, the mentor(s) is/are in charge of the language.
180     </p>
181    
182     <p>
183     If a translated document is contributed, but the language in itself is
184     not supported, the Gentoo Documentation Team will not publish it
185     officially. In this case the document will stay unlinked until an official
186     translation team of that language is formed.
187     </p>
188    
189     <p>
190     When a language is officially supported, but the team doesn't have any
191     members or no one wants to take on the responsibilities of the lead
192     translator, all links to the documents will be removed from the site.
193     However, the documents will stay available in case the language becomes
194     officially supported again.
195     </p>
196 zhen 1.1
197 swift 1.3 </body>
198     </section>
199 zhen 1.1 </chapter>
200    
201 swift 1.3 <chapter>
202     <title>Gentoo Documentation Guidelines</title>
203     <section>
204     <title>Legal Issues</title>
205     <body>
206    
207     <p>
208     Every document published by the Gentoo Documentation Project must be
209     licensed by the <uri
210     link="http://creativecommons.org/licenses/by-sa/2.0/">Creative Commons
211     Attribution-ShareAlike License</uri>.
212     </p>
213    
214     <p>
215     Every document must have the following tag inside its GuideXML
216     sourcecode between the <c>&lt;/abstract&gt;</c> and the <c>&lt;version&gt;</c>
217     tags:
218     </p>
219    
220     <pre caption = "Licensing notice for the Gentoo Documentation">
221     &lt;/abstract&gt;
222     <i>
223     &lt;!-- The content of this document is licensed under the CC-BY-SA license --&gt;
224     &lt;!-- See http://creativecommons.org/licenses/by-sa/2.0 --&gt;
225     &lt;license/&gt;
226     </i>
227     &lt;version&gt;...&lt;/version&gt;
228     </pre>
229    
230     </body>
231     </section>
232     <section>
233     <title>Bugs and Updates</title>
234     <body>
235    
236     <p>
237     Every bug reported on <uri link="http://bugs.gentoo.org">bugs.gentoo.org</uri>
238     should be handled as fast as possible. If a bug cannot be handled
239     in a timely fashion, the reporter of that bug should be informed about
240 swift 1.8 this using a comment on the bug and the bug should be registered in the
241     <uri link="/proj/en/gdp/doc/metadoc-guide.xml">metadoc.xml</uri> file, if
242     applicable. The tactical or operational manager can decide that a bug has a
243     higher priority and should be handled first before any other task the assingee
244     is responsible of.
245 swift 1.3 </p>
246    
247     <p>
248     Whenever a Gentoo Documentation Team member takes care of a bug, he or
249     she should assign the bug to herself/himself, but make sure that
250     <c>docs-team@gentoo.org</c> is on the Cc-list. Unless with the consent
251     of the operational manager, a bug may not be taken away from another
252     Gentoo Documentation Team member without their approval.
253     </p>
254    
255     </body>
256     </section>
257     <section>
258     <title>Document Development</title>
259     <body>
260    
261     <p>
262 neysx 1.9 Every document the Gentoo Documentation Team develops can be developed as the
263     related parties see fit. However, when the document is finished, it should be
264     transformed into <uri link="/doc/en/xml-guide.xml">GuideXML</uri> and put
265 swift 1.8 available on the Gentoo CVS infrastructure. It must also be registered in the
266     <uri link="/proj/en/gdp/doc/metadoc-guide.xml">metadoc.xml</uri> file if
267     applicable.
268 swift 1.3 </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     All changes in XML formatting should lead to version (and date) bumps only in
289     case the layout of the document changes.
290     </p>
291    
292     <p>
293     Whether or not to increment the major version number instead of minor version
294     number or other is up to the editor.
295     </p>
296    
297     <p>
298     Every update of a translation should copy the new version information
299     verbatim from the master English document so fully synchronised
300     translations have the same version information.
301     </p>
302    
303     </body>
304     </section>
305     <section>
306     <title>Reviewing and Committing</title>
307     <body>
308    
309     <p>
310     To keep a high-pace development cycle of the documentation, technical or
311     intrusive changes to documents can be propagated immediately to the document
312     <e>if</e> the editor is 100% confident his changes are correct and working. If
313     you are not 100% confident (for instance because a user has told you how to fix
314     it but you cannot verify yourself), have the change reviewed by a Gentoo
315     Developer that can verify the change.
316     </p>
317    
318     <p>
319     High volume, technical or intrusive changes must be accompanied by a bugreport
320     on <uri>http://bugs.gentoo.org</uri>. This bugnumber <e>must</e> be mentioned in
321     the CVS log to allow backtracing of changes.
322     </p>
323    
324     <p>
325     If a bugfix consists out of both content as internal coding changes,
326     both changes must be committed seperately so that translators can easily
327     view the important changes (content) and ignore the coding changes.
328     </p>
329    
330     <p>
331     In case of a translation, the lead translator of the language is
332 vapier 1.4 responsible for the document. Only he may commit the document to CVS
333     unless he is currently "in training", in which case his or her
334 swift 1.3 mentor should commit it.
335     </p>
336    
337     </body>
338     </section>
339     <section>
340     <title>Sanctions</title>
341     <body>
342    
343     <p>
344     Although this has never been necessary, it is still important to list this in
345     the policy - even though it is hateful. Anyway, documentation developers that
346     misuse their position by
347     </p>
348    
349     <ul>
350     <li>deliberately providing wrong information to users or developers</li>
351     <li>deliberately writing flawed documentation</li>
352     <li>deliberately corrupting documents</li>
353     <li>
354     deliberately go against the decisions made policy-wise or through a
355     consensus-model on the Gentoo Documentation mailinglist
356     </li>
357     <li>
358     not performing at all for a long time without informing the GDP and without
359     replying to the operational manager's request for a status update
360     </li>
361     </ul>
362    
363     <p>
364 neysx 1.9 will be reported to the <uri link="/proj/en/devrel/">Gentoo Developer
365 swift 1.3 Relations</uri> project.
366     </p>
367 zhen 1.1
368 swift 1.3 </body>
369     </section>
370 zhen 1.1 </chapter>
371 swift 1.3
372 zhen 1.1 <chapter>
373 swift 1.3 <title>Documentation Team Recruitement</title>
374     <section>
375     <title>Contributors, Authors, Translators</title>
376     <body>
377    
378     <p>
379     Everyone interested in contributing documentation, editing existing
380     documentation, writing new documentation or translating documentation is
381     welcome to join the team. There are no rules or strings attached to
382     this. Just make sure you are subscribed to <c>gentoo-doc@gentoo.org</c>
383     and you have fully read this policy and understand it.
384     </p>
385    
386     </body>
387     </section>
388     <section>
389     <title>Gentoo Documentation Developer</title>
390     <body>
391    
392     <p>
393     As a Gentoo documentation developer should know everything in the <uri
394 swift 1.6 link="/proj/en/devrel/handbook/handbook.xml?part=3&amp;chap=1">Gentoo Ebuild
395 swift 1.7 Policy</uri> even though you're not submitting ebuilds. This is all needed to
396     ensure our userbase that no Gentoo developer gives wrong information about
397     critical things.
398 swift 1.3 </p>
399    
400     <p>
401     Contact the operational manager of the Gentoo Documentation Project. He
402     will ask you for your coordinates and other information and then arrange
403     a mentor for you who will guide you through the first days or weeks as
404     developer.
405     </p>
406    
407     <p>
408     You will be given a Gentoo e-mail address and be appointed to one or
409     more subprojects. During the initial days or weeks, you should ask your
410 vapier 1.4 mentor as much as possible, preferably have him double-check everything
411 swift 1.3 you do. If your function requires CVS access, you will only receive it
412     when your mentor deems it appropriate. Until then, your mentor is in
413     charge of the CVS commits.
414     </p>
415    
416     </body>
417     </section>
418     <section>
419     <title>(Follow-Up) Lead Translator</title>
420     <body>
421    
422     <p>
423     Becoming a (follow-up) lead translator shouldn't be held lightly. You are
424     responsible for every translated document and final reviewing. The lead
425     translator will make certain that the translated documents are
426     grammatically and syntactically perfect.
427     </p>
428    
429     <p>
430     In order to become a Gentoo (follow-up) lead translator you must be a Gentoo
431     developer.
432     </p>
433    
434     <p>
435     During your "training" period you are a (follow-up) lead translator and
436     should act upon it. All guidelines regarding (follow-up) lead translators
437     apply.
438     </p>
439 zhen 1.1
440 swift 1.3 </body>
441     </section>
442 zhen 1.1 </chapter>
443     </guide>

  ViewVC Help
Powered by ViewVC 1.1.20