/[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.27 - (hide annotations) (download) (as text)
Tue Nov 29 19:01:23 2011 UTC (2 years, 8 months ago) by swift
Branch: MAIN
Changes since 1.26: +14 -7 lines
File MIME type: application/xml
Introduce support for version 3.0 in our documents

From the GDP point-of-view, the CC-BY-SA 3.0 license also fully matches the projects' principles. The original choice for
2.5 was because it was, at that time, the latest version. With the Gentoo wiki now using CC-BY-SA 3.0, we now also support
this version, allowing for documents to be replicated between the two sources.

1 zhen 1.1 <?xml version='1.0' encoding="UTF-8"?>
2 swift 1.27 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/proj/en/gdp/doc/doc-policy.xml,v 1.26 2011/09/29 12:55:51 cam Exp $ -->
3 zhen 1.1 <!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
4    
5 nightmorph 1.24 <guide>
6 zhen 1.1 <title>Gentoo Linux Documentation Policy</title>
7 neysx 1.23
8 neysx 1.22 <author title="Author">
9     <mail link="neysx@gentoo.org">Xavier Neys</mail>
10 swift 1.3 </author>
11 neysx 1.23 <author title="Author">John P. Davis</author>
12 swift 1.3 <author title="Author">
13 neysx 1.21 <mail link="swift@gentoo.org">Sven Vermeulen</mail>
14 swift 1.3 </author>
15     <author title="Editor">
16 neysx 1.21 <mail link="dberkholz@gentoo.org">Donnie Berkholz</mail>
17 swift 1.3 </author>
18    
19 zhen 1.1 <abstract>
20 swift 1.3 This document contains the Gentoo Documentation Policy, which is the
21     base document which all Gentoo Documentation developers and
22 swift 1.16 Contributors should know and exercise.
23 zhen 1.1 </abstract>
24    
25 nightmorph 1.24 <!-- The content of this document is licensed under the CC-BY-SA license -->
26     <!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
27 swift 1.3 <license/>
28    
29 swift 1.27 <version>8</version>
30     <date>2011-11-29</date>
31 zhen 1.1
32     <chapter>
33 swift 1.3 <title>Introduction</title>
34     <section>
35     <title>Introduction</title>
36     <body>
37    
38     <p>
39 neysx 1.21 The Gentoo Linux Documentation team aspires to create exceptionally
40     professional documentation that is immediately clear and concise to the
41     end user. In order to fulfill this goal, we have very specific rules and
42 swift 1.25 guidelines that our documentation must go through prior to
43 swift 1.16 dissemination on our website, or elsewhere.
44 swift 1.3 </p>
45    
46     </body>
47     </section>
48     <section>
49     <title>Covered Topics</title>
50     <body>
51    
52     <p>
53 neysx 1.21 This policy will cover the following topics:
54 swift 1.3 </p>
55    
56     <ul>
57     <li>Documentation Project Team Organization</li>
58     <li>Documentation Guidelines</li>
59 swift 1.13 <li>Documentation Team Recruitment</li>
60 swift 1.3 </ul>
61 zhen 1.1
62 swift 1.3 </body>
63     </section>
64 zhen 1.1 </chapter>
65    
66     <chapter>
67 swift 1.3 <title>Documentation Project Team Organization</title>
68     <section>
69     <title>Organization</title>
70     <body>
71    
72     <p>
73 swift 1.25 The Gentoo Documentation Project Team consists of editors and authors, working
74     on our main documentation and its translations. Like most other Gentoo projects,
75 cam 1.26 it is led by a project lead whose additional job is to look after the team and
76 swift 1.25 its resources in general (such as focusing on recruitment when necessary and
77 cam 1.26 taking final decisions when consensus about doc-related issues cannot be found
78     otherwise).
79 swift 1.3 </p>
80    
81     <p>
82 swift 1.25 When the Gentoo Documentation Team launches any subprojects, you will find its
83     mission on our <uri link="/proj/en/gdp/">GDP Project Webpage</uri>, along with
84     their respective project leads.
85 swift 1.3 </p>
86    
87     </body>
88     </section>
89     <section>
90     <title>Documentation Project Team Members</title>
91     <body>
92    
93     <p>
94     Every member of the Gentoo Documentation Project must be subscribed to
95 neysx 1.23 the <mail link="gentoo-doc+subscribe@gentoo.org">gentoo-doc@gentoo.org</mail>
96 swift 1.3 mailing list. This mailing list will be used to discuss all
97     documentation-related issues. This mailing list is open to all interested
98     parties, developer or not.
99     </p>
100    
101     <p>
102 swift 1.11 Every member of the Gentoo Documentation Project must be part of the
103 neysx 1.23 <mail>docs-team@gentoo.org</mail> alias. This alias is <e>only</e> used by <uri
104 neysx 1.9 link="http://bugs.gentoo.org">bugs.gentoo.org</uri> to inform the documentation
105 swift 1.11 team about bugs regarding the Gentoo Documentation. You can add yourself by
106 swift 1.25 editing <path>/var/mail/alias/misc/docs-team</path> on dev.gentoo.org. Please do
107     <e>not</e> use this address to try and contact the team - you can contact us
108     through the mailinglist, IRC or by mailing the project lead or any other member.
109 swift 1.3 </p>
110    
111     <p>
112 swift 1.25 Members of the Gentoo Documentation Team are frequently online in
113     <c>#gentoo-doc</c> on <uri link="http://www.freenode.net">irc.freenode.net</uri>.
114 swift 1.3 </p>
115    
116     <p>
117 swift 1.25 Depending on the assignment or responsibilities, a member may have CVS
118     access to <c>cvs.gentoo.org</c>. Interested non-developers can use the
119     <uri link="http://anoncvs.gentoo.org">anonymous CVS server</uri>
120     to help out with the documentation. It contains the same files as our CVS
121     server but is a few minutes late.
122 swift 1.3 </p>
123    
124     </body>
125     </section>
126     <section>
127     <title>Documentation Translation Teams</title>
128     <body>
129    
130     <p>
131 swift 1.15 Every language should be backed up by an official Translation Team. This
132 neysx 1.21 team is led by a <e>Lead Translator</e> and perhaps a <e>Follow-On Lead
133 swift 1.25 Translator</e>, who both have CVS commit access. Organization of the
134     translations is handled by the lead translator as he or she sees fit, as
135     long as the committed translations follow this policy.
136 swift 1.3 </p>
137    
138     <p>
139 swift 1.15 If a translated document for an unsupported language is contributed, the Gentoo
140 neysx 1.23 Documentation Team will publish it as-is. Such documents will not be linked to
141     the website until an official Translation Team of that language is formed, but
142     they will be available on our site and in CVS.
143 swift 1.3 </p>
144    
145     <p>
146 neysx 1.21 For more information Gentoo document translations, please consult the
147 swift 1.15 <uri link="/proj/en/gdp/doc/translators-howto.xml">
148 neysx 1.21 Translators Howto for Gentoo Documentation</uri> and the
149 swift 1.15 <uri link="/proj/en/gdp/international.xml">
150     GDP Internationalisation Subproject</uri> page.
151     </p>
152    
153 swift 1.3 </body>
154     </section>
155 zhen 1.1 </chapter>
156    
157 swift 1.3 <chapter>
158     <title>Gentoo Documentation Guidelines</title>
159     <section>
160     <title>Legal Issues</title>
161     <body>
162    
163     <p>
164     Every document published by the Gentoo Documentation Project must be
165 neysx 1.21 licensed by the <uri
166 swift 1.27 link="http://creativecommons.org/licenses/by-sa/3.0/">Creative Commons
167     Attribution-ShareAlike License</uri>, preferably the latest version (although
168     earlier versions are supported too).
169 swift 1.3 </p>
170    
171     <p>
172     Every document must have the following tag inside its GuideXML
173 swift 1.13 source code between the <c>&lt;/abstract&gt;</c> and the <c>&lt;version&gt;</c>
174 swift 1.3 tags:
175     </p>
176    
177 neysx 1.23 <pre caption="Licensing notice for the Gentoo Documentation">
178 swift 1.3 &lt;/abstract&gt;
179     <i>
180     &lt;!-- The content of this document is licensed under the CC-BY-SA license --&gt;
181 swift 1.27 &lt;!-- See http://creativecommons.org/licenses/by-sa/3.0 --&gt;
182     &lt;license version="3.0"/&gt;
183 swift 1.3 </i>
184     &lt;version&gt;...&lt;/version&gt;
185     </pre>
186    
187 swift 1.27 <p>
188     If the 2.5 version is used, the tag can be either <c>&lt;license /&gt;</c> or
189     <c>&lt;license version="2.5" /&gt;</c>. In either case should the comment be
190     updated to refer to the correct version URL.
191     </p>
192    
193 swift 1.3 </body>
194     </section>
195     <section>
196     <title>Bugs and Updates</title>
197     <body>
198    
199     <p>
200     Every bug reported on <uri link="http://bugs.gentoo.org">bugs.gentoo.org</uri>
201 neysx 1.21 should be handled as fast as possible. If a bug cannot be handled
202 swift 1.3 in a timely fashion, the reporter of that bug should be informed about
203 neysx 1.21 this using a comment on the bug, and the bug should be registered in the
204     <uri link="/proj/en/gdp/doc/metadoc-guide.xml">metadoc.xml</uri> file, if
205 swift 1.25 applicable.
206 swift 1.3 </p>
207    
208     <p>
209 neysx 1.23 Whenever a Gentoo Documentation Team member takes care of a bug, he or she
210     should assign the bug to herself/himself, but make sure that
211     <mail>docs-team@gentoo.org</mail> is on the Cc-list. A bug may not be taken
212 swift 1.25 away from another Gentoo Documentation Team member without their approval
213     unless consent has been received from the project lead.
214 swift 1.3 </p>
215    
216     </body>
217     </section>
218     <section>
219     <title>Document Development</title>
220     <body>
221    
222     <p>
223 swift 1.15 Every Gentoo Documentation Team may handle documentation development as it sees
224 neysx 1.21 fit. However, when the document is finished, it should be transformed into
225     <uri link="/doc/en/xml-guide.xml">GuideXML</uri> and made available on the
226 swift 1.15 Gentoo CVS infrastructure. It must also be registered in the
227 swift 1.8 <uri link="/proj/en/gdp/doc/metadoc-guide.xml">metadoc.xml</uri> file if
228     applicable.
229 swift 1.3 </p>
230    
231     <p>
232 neysx 1.21 When a new document is started or a big change is needed, a bug should be filed
233 swift 1.3 at <uri link="http://bugs.gentoo.org">bugs.gentoo.org</uri>
234     concerning the development of this document. If there is already a bug
235     in the database that requests a change to the documentation, a new bug
236     does not have to be filed. Grammatical, syntactical or small changes
237 neysx 1.21 do not require a bug to be filed on <uri
238 swift 1.3 link="http://bugs.gentoo.org">bugs.gentoo.org</uri> as well.
239     </p>
240    
241     <p>
242 neysx 1.23 All changes in contents of the document, except for typo fixes in text itself
243     or in the comments to code listings, should lead to version number and date
244     increase. Note that the change of a Code Listings should definitely cause an
245     increase of the version number and date.
246 swift 1.3 </p>
247    
248     <p>
249 neysx 1.23 All changes in XML formatting should lead to version and date bumps only in
250     case the layout of the HTML document changes.
251 swift 1.3 </p>
252    
253     <p>
254 swift 1.25 Versions should always be handled as integers, so a version bump of version
255     <c>2</c> leads to version <c>3</c>. Historical versions that use the major and
256     minor syntax should be converted to the next integer on the next update, so
257     version <c>3.2</c> becomes version <c>4</c>.
258 swift 1.3 </p>
259    
260     <p>
261 neysx 1.23 Every update of a translation should use the version and date information
262     verbatim from the master English document so fully synchronised translations
263     have the same version and date.
264 swift 1.3 </p>
265    
266     </body>
267     </section>
268     <section>
269     <title>Reviewing and Committing</title>
270     <body>
271    
272     <p>
273 swift 1.15 To maintain a high-paced documentation development cycle, technical or
274     intrusive changes to documents can be propagated immediately to the document.
275     This is allowed only <e>if</e> the editor is absolutely confident the changes
276 swift 1.25 are functionally correct. If you are not absolutely confident (for instance because a
277 swift 1.15 user has told you how to fix it but you cannot verify yourself), have the
278 swift 1.25 changes reviewed by a third person that can verify the changes are apt.
279 swift 1.3 </p>
280    
281     <p>
282 swift 1.15 High-volume, technical or intrusive changes must be accompanied by a bug report
283     on <uri>http://bugs.gentoo.org</uri>. This bug number <e>must</e> be mentioned
284 swift 1.13 in the CVS log to allow backtracing of changes.
285 swift 1.3 </p>
286    
287     <p>
288 swift 1.15 If a bugfix includes changes to content as well as internal coding changes,
289     both changes must be committed separately. This allows translators to focus
290     on the relevant changes regarding content and ignore the coding changes.
291 swift 1.3 </p>
292    
293     </body>
294     </section>
295     <section>
296     <title>Sanctions</title>
297     <body>
298    
299     <p>
300 swift 1.25 Malicious conduct by developers has not been an issue before. However, it
301     should be noted that documentation developers that misuse their position by
302 swift 1.3 </p>
303    
304     <ul>
305     <li>deliberately providing wrong information to users or developers</li>
306     <li>deliberately writing flawed documentation</li>
307     <li>deliberately corrupting documents</li>
308     <li>
309     deliberately go against the decisions made policy-wise or through a
310     consensus-model on the Gentoo Documentation mailinglist
311     </li>
312 swift 1.25 <li>not performing at all for a long time without informing the GDP</li>
313 swift 1.3 </ul>
314    
315     <p>
316 neysx 1.9 will be reported to the <uri link="/proj/en/devrel/">Gentoo Developer
317 swift 1.3 Relations</uri> project.
318     </p>
319 zhen 1.1
320 swift 1.3 </body>
321     </section>
322 zhen 1.1 </chapter>
323 swift 1.3
324 zhen 1.1 <chapter>
325 swift 1.16 <title>Documentation Team Recruitment</title>
326 swift 1.3 <section>
327     <title>Contributors, Authors, Translators</title>
328     <body>
329    
330     <p>
331     Everyone interested in contributing documentation, editing existing
332     documentation, writing new documentation or translating documentation is
333 neysx 1.23 welcome to send their contributions. There are no rules or strings attached to
334     this. Just make sure you are subscribed to <mail>gentoo-doc@gentoo.org</mail>,
335 swift 1.3 and you have fully read this policy and understand it.
336     </p>
337    
338     </body>
339     </section>
340     <section>
341 swift 1.11 <title>Recruitment Process</title>
342 swift 1.3 <body>
343    
344     <p>
345 swift 1.25 The Documentation Project uses the recruitment process outlined below.
346     We have opted for this recruitment process to assure ourselves that the recruit
347     is well informed about the Gentoo Documentation Policy and the Gentoo Coding
348     Style. It has proven to be quite effective even though many contributors see it
349     as a too large burden to cross.
350 swift 1.3 </p>
351    
352     <p>
353 swift 1.11 This recruitment process is meant only for requests to the Gentoo Documentation
354 neysx 1.23 Repository through CVS. Being listed as the maintainer or point of contact for
355 swift 1.25 a certain document or range of documents does not require developer access.
356 swift 1.11 </p>
357    
358     </body>
359     </section>
360     <section>
361     <title>Phase 1: Contributions</title>
362     <body>
363    
364     <p>
365     No recruitment process starts without investigating the contributions done
366     already to the Gentoo Documentation Project. The number of contributions must be
367 neysx 1.21 large to assure a good knowledge of GuideXML, Coding Style and policy. The
368 swift 1.25 contribution period must be large as well to allow the contributor to find out
369     if he can provide continuous support for the Gentoo Documentation Project.
370 swift 1.11 </p>
371    
372     <p>
373     An update constitutes a non-trivial update to any documentation, translation or
374 swift 1.25 otherwise, completely written or edited by the contributor and committed after
375     review by any existing documentation developer.
376 swift 1.3 </p>
377    
378     <p>
379 neysx 1.21 If you feel that you have shown sufficient amount of contributions, contact
380 swift 1.25 the project lead of the Gentoo Documentation Project. He will ask you for your
381     coordinates and other information, and then arrange for the next phase to be
382     started.
383 swift 1.3 </p>
384    
385     </body>
386     </section>
387     <section>
388 neysx 1.23 <title>Phase 2: Start the Recruitment Process</title>
389 swift 1.3 <body>
390    
391     <p>
392 swift 1.25 During this period, submitted patches are not edited by a documentation
393     developer anymore, but are either committed as-is or refused. The recruit is
394     also assigned to a documentation developer (the mentor) which will guide him
395     through these last phases.
396 swift 1.11 </p>
397    
398     <p>
399     The quality of the contributions are in this phase most important - every patch
400     that does not follow the Documentation Policy, Coding Style or other guideline
401 swift 1.25 that affects the document is tackled by the recruit himself with help of the
402     mentor.
403 swift 1.3 </p>
404    
405     <p>
406 swift 1.25 During this period, the recruit:
407 swift 1.3 </p>
408    
409 swift 1.11 <ul>
410     <li>
411 swift 1.25 is advised to learn about Gentoo's inner workings.
412     This is required as he or she will be asked later on to answer Gentoo's <uri
413 swift 1.11 link="/proj/en/devrel/quiz/staff-quiz.txt">Staffing Quiz</uri>.
414     </li>
415     <li>
416 neysx 1.21 will be asked to fill in the <uri
417 swift 1.11 link="/proj/en/gdp/doc/doc-quiz.xml">Gentoo Documentation Project
418 swift 1.25 Quiz</uri>. He or she needs to successfully pass this entire quiz
419     (all questions) before we can continue with the next Phase.
420 swift 1.11 </li>
421     </ul>
422    
423     </body>
424     </section>
425     <section>
426     <title>Phase 3: Gentoo Recruitment</title>
427     <body>
428    
429 swift 1.3 <p>
430 swift 1.25 When Phase 2 is finished, the project lead will contact <uri
431 neysx 1.23 link="/proj/en/devrel/">Developer Relations</uri> and give a final "Go!" for the
432 swift 1.25 Gentoo recruitment process after which the recruit will be given access to the
433     necessary Gentoo infrastructural services (like the documentation repository).
434     </p>
435    
436     </body>
437     </section>
438     <section>
439     <title>Recruitment of Existing Gentoo Developers</title>
440     <body>
441    
442     <p>
443     If the recruit is already a Gentoo Developer, the same recruitment process is
444     followed, but the staffing quiz is not necessary anymore. However, the <uri
445     link="/proj/en/gdp/doc/doc-quiz.xml">Gentoo Documentation Project Quiz</uri> is
446     still mandatory.
447 swift 1.3 </p>
448 zhen 1.1
449 swift 1.3 </body>
450     </section>
451 zhen 1.1 </chapter>
452     </guide>

  ViewVC Help
Powered by ViewVC 1.1.20