/[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.28 - (show annotations) (download) (as text)
Sun Mar 31 13:00:52 2013 UTC (12 months, 2 weeks ago) by swift
Branch: MAIN
CVS Tags: HEAD
Changes since 1.27: +23 -26 lines
File MIME type: application/xml
Update GDP policy to be more in line with recent developments, resources etc. See gentoo-doc mailinglist for more information

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

  ViewVC Help
Powered by ViewVC 1.1.20