/[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.23 - (show annotations) (download) (as text)
Mon Mar 5 12:57:48 2007 UTC (7 years, 6 months ago) by neysx
Branch: MAIN
Changes since 1.22: +49 -49 lines
File MIME type: application/xml
Spring refresh

1 <?xml version='1.0' encoding="UTF-8"?>
2 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/proj/en/gdp/doc/doc-policy.xml,v 1.22 2006/09/28 13:21:22 neysx Exp $ -->
3 <!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
4
5 <guide link="doc-policy.xml">
6
7 <title>Gentoo Linux Documentation Policy</title>
8
9 <author title="Author">
10 <mail link="neysx@gentoo.org">Xavier Neys</mail>
11 </author>
12 <author title="Author">John P. Davis</author>
13 <author title="Author">
14 <mail link="swift@gentoo.org">Sven Vermeulen</mail>
15 </author>
16 <author title="Editor">
17 <mail link="dberkholz@gentoo.org">Donnie Berkholz</mail>
18 </author>
19
20 <!-- The content of this document is licensed under the CC-BY-SA license -->
21 <!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
22
23 <abstract>
24 This document contains the Gentoo Documentation Policy, which is the
25 base document which all Gentoo Documentation developers and
26 Contributors should know and exercise.
27 </abstract>
28
29 <license/>
30
31 <version>4</version>
32 <date>2007-02-26</date>
33
34 <chapter>
35 <title>Introduction</title>
36 <section>
37 <title>Introduction</title>
38 <body>
39
40 <p>
41 The Gentoo Linux Documentation team aspires to create exceptionally
42 professional documentation that is immediately clear and concise to the
43 end user. In order to fulfill this goal, we have very specific rules and
44 guidelines that <e>all</e> documentation must go through prior to
45 dissemination on our website, or elsewhere.
46 </p>
47
48 </body>
49 </section>
50 <section>
51 <title>Covered Topics</title>
52 <body>
53
54 <p>
55 This policy will cover the following topics:
56 </p>
57
58 <ul>
59 <li>Documentation Project Team Organization</li>
60 <li>Documentation Guidelines</li>
61 <li>Documentation Team Recruitment</li>
62 </ul>
63
64 </body>
65 </section>
66 </chapter>
67
68 <chapter>
69 <title>Documentation Project Team Organization</title>
70 <section>
71 <title>Organization</title>
72 <body>
73
74 <p>
75 The Gentoo Documentation Project Team is split into several smaller teams
76 that work in tandem with each other. Each smaller team represents an active
77 development team of a Gentoo Documentation Subproject.
78 </p>
79
80 <!--
81 <p>
82 The Gentoo Documentation Project is strategically led by a top-level Manager
83 as required by the <uri link="/doc/en/management-structure.xml">Gentoo
84 Management Structure</uri>. This document also describes the responsibilities
85 of the Strategic Manager with respect to Gentoo Linux.
86 </p>
87 -->
88
89 <p>
90 For day-to-day managerial tasks, the Gentoo Documentation Project has an
91 Operational Manager. This person keeps track of all short-term tasks
92 related to documentation. The Operational Manager and Strategic Manager can be
93 one and the same if the Strategic 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>Xavier Neys</ti>
109 <ti><mail link="neysx@gentoo.org">neysx</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 <!--
119 <p>
120 Every subproject has a Strategic Manager of its own, and may have an
121 Operational Manager if deemed appropriate. His responsibilities to the Gentoo
122 Documentation Project (GDP) are listed in the <e>Manager responsibilities</e>
123 section of the <uri
124 link="/doc/en/management-structure.xml#doc_chap1_sect5">Gentoo Management
125 Structure</uri> document.
126 </p>
127 -->
128
129 <p>
130 Every subproject of the Gentoo Documentation Team is listed on the
131 <uri link="/proj/en/gdp/">GDP Webpage</uri>, along with their respective
132 Strategic Managers.
133 </p>
134
135 <p>
136 The decision on adding a subproject is in the hands of the Strategic Manager.
137 </p>
138
139 </body>
140 </section>
141 <section>
142 <title>Documentation Project Team Members</title>
143 <body>
144
145 <p>
146 Every member of the Gentoo Documentation Project must be subscribed to
147 the <mail link="gentoo-doc+subscribe@gentoo.org">gentoo-doc@gentoo.org</mail>
148 mailing list. This mailing list will be used to discuss all
149 documentation-related issues. This mailing list is open to all interested
150 parties, developer or not.
151 </p>
152
153 <p>
154 Every member of the Gentoo Documentation Project must be part of the
155 <mail>docs-team@gentoo.org</mail> alias. This alias is <e>only</e> used by <uri
156 link="http://bugs.gentoo.org">bugs.gentoo.org</uri> to inform the documentation
157 team about bugs regarding the Gentoo Documentation. You can add yourself by
158 editing <path>/var/mail/alias/misc/docs-team</path> on dev.gentoo.org.
159 </p>
160
161 <p>
162 Members of the Gentoo Documentation Team should be available at
163 <c>#gentoo-doc</c> on <uri link="http://www.freenode.net">irc.freenode.net</uri>
164 whenever they are online.
165 </p>
166
167 <p>
168 Depending on the assignment or responsibilities, a member may have limited CVS
169 access to <c>cvs.gentoo.org</c>. Full CVS access is restricted to Gentoo
170 Developers. An <uri link="http://anoncvs.gentoo.org">anonymous CVS server</uri>
171 is available. It contains the same files as our CVS server but is a few minutes
172 late.
173 </p>
174
175 </body>
176 </section>
177 <section>
178 <title>Documentation Translation Teams</title>
179 <body>
180
181 <p>
182 Every language should be backed up by an official Translation Team. This
183 team is led by a <e>Lead Translator</e> and perhaps a <e>Follow-On Lead
184 Translator</e>, who both have CVS commit access. If for any reason the
185 <e>Lead Translator</e> cannot perform his duties, the <e>Follow-On Lead
186 Translator</e> is in charge. If the <e>Follow-On</e> is unavailable, the
187 mentor(s) is/are in charge of the language.
188 </p>
189
190 <p>
191 If a translated document for an unsupported language is contributed, the Gentoo
192 Documentation Team will publish it as-is. Such documents will not be linked to
193 the website until an official Translation Team of that language is formed, but
194 they will be available on our site and in CVS.
195 </p>
196
197 <p>
198 When a language is officially supported, but the team does not have any
199 members willing to take on the responsibilities of the <e>Lead
200 Translator</e>, all links to the documents will be removed from the site.
201 However, the documents will stay available in case the language becomes
202 officially supported again.
203 </p>
204
205 <p>
206 For more information Gentoo document translations, please consult the
207 <uri link="/proj/en/gdp/doc/translators-howto.xml">
208 Translators Howto for Gentoo Documentation</uri> and the
209 <uri link="/proj/en/gdp/international.xml">
210 GDP Internationalisation Subproject</uri> page.
211 </p>
212
213 </body>
214 </section>
215 </chapter>
216
217 <chapter>
218 <title>Gentoo Documentation Guidelines</title>
219 <section>
220 <title>Legal Issues</title>
221 <body>
222
223 <p>
224 Every document published by the Gentoo Documentation Project must be
225 licensed by the <uri
226 link="http://creativecommons.org/licenses/by-sa/2.5/">Creative Commons
227 Attribution-ShareAlike License</uri>.
228 </p>
229
230 <p>
231 Every document must have the following tag inside its GuideXML
232 source code between the <c>&lt;/abstract&gt;</c> and the <c>&lt;version&gt;</c>
233 tags:
234 </p>
235
236 <pre caption="Licensing notice for the Gentoo Documentation">
237 &lt;/abstract&gt;
238 <i>
239 &lt;!-- The content of this document is licensed under the CC-BY-SA license --&gt;
240 &lt;!-- See http://creativecommons.org/licenses/by-sa/2.5 --&gt;
241 &lt;license/&gt;
242 </i>
243 &lt;version&gt;...&lt;/version&gt;
244 </pre>
245
246 </body>
247 </section>
248 <section>
249 <title>Bugs and Updates</title>
250 <body>
251
252 <p>
253 Every bug reported on <uri link="http://bugs.gentoo.org">bugs.gentoo.org</uri>
254 should be handled as fast as possible. If a bug cannot be handled
255 in a timely fashion, the reporter of that bug should be informed about
256 this using a comment on the bug, and the bug should be registered in the
257 <uri link="/proj/en/gdp/doc/metadoc-guide.xml">metadoc.xml</uri> file, if
258 applicable. The Strategic or Operational Manager may decide that a bug has a
259 higher priority and should be addressed ahead any other task the assignee
260 is responsible for.
261 </p>
262
263 <p>
264 Whenever a Gentoo Documentation Team member takes care of a bug, he or she
265 should assign the bug to herself/himself, but make sure that
266 <mail>docs-team@gentoo.org</mail> is on the Cc-list. A bug may not be taken
267 away from another Gentoo Documentation Team member without their approval;
268 unless consent has been received from the Operational Manager.
269 </p>
270
271 </body>
272 </section>
273 <section>
274 <title>Document Development</title>
275 <body>
276
277 <p>
278 Every Gentoo Documentation Team may handle documentation development as it sees
279 fit. However, when the document is finished, it should be transformed into
280 <uri link="/doc/en/xml-guide.xml">GuideXML</uri> and made available on the
281 Gentoo CVS infrastructure. It must also be registered in the
282 <uri link="/proj/en/gdp/doc/metadoc-guide.xml">metadoc.xml</uri> file if
283 applicable.
284 </p>
285
286 <p>
287 When a new document is started or a big change is needed, a bug should be filed
288 at <uri link="http://bugs.gentoo.org">bugs.gentoo.org</uri>
289 concerning the development of this document. If there is already a bug
290 in the database that requests a change to the documentation, a new bug
291 does not have to be filed. Grammatical, syntactical or small changes
292 do not require a bug to be filed on <uri
293 link="http://bugs.gentoo.org">bugs.gentoo.org</uri> as well.
294 </p>
295
296 <p>
297 All changes in contents of the document, except for typo fixes in text itself
298 or in the comments to code listings, should lead to version number and date
299 increase. Note that the change of a Code Listings should definitely cause an
300 increase of the version number and date.
301 </p>
302
303 <p>
304 All changes in XML formatting should lead to version and date bumps only in
305 case the layout of the HTML document changes.
306 </p>
307
308 <p>
309 Whether or not to increment the major version number instead of minor version
310 number or other is up to the editor.
311 </p>
312
313 <p>
314 Every update of a translation should use the version and date information
315 verbatim from the master English document so fully synchronised translations
316 have the same version and date.
317 </p>
318
319 </body>
320 </section>
321 <section>
322 <title>Reviewing and Committing</title>
323 <body>
324
325 <p>
326 To maintain a high-paced documentation development cycle, technical or
327 intrusive changes to documents can be propagated immediately to the document.
328 This is allowed only <e>if</e> the editor is absolutely confident the changes
329 are functional. If you are not absolutely confident (for instance because a
330 user has told you how to fix it but you cannot verify yourself), have the
331 changes reviewed by a Gentoo Developer that can verify the changes are apt.
332 </p>
333
334 <p>
335 High-volume, technical or intrusive changes must be accompanied by a bug report
336 on <uri>http://bugs.gentoo.org</uri>. This bug number <e>must</e> be mentioned
337 in the CVS log to allow backtracing of changes.
338 </p>
339
340 <p>
341 If a bugfix includes changes to content as well as internal coding changes,
342 both changes must be committed separately. This allows translators to focus
343 on the relevant changes regarding content and ignore the coding changes.
344 </p>
345
346 <p>
347 If the document in question is a translation, the <e>Lead Translator</e> of the
348 affected language is responsible for the document. Only the <e>Lead
349 Translator</e> and his follow-on may commit the document to the CVS repository.
350 However, if the <e>Lead Translator</e> is currently "in training", the
351 trainee's mentor should commit the changes.
352 </p>
353
354 </body>
355 </section>
356 <section>
357 <title>Sanctions</title>
358 <body>
359
360 <p>
361 Malicious conduct by developers has never been an issue. However, it should be
362 noted that documentation developers that misuse their position by
363 </p>
364
365 <ul>
366 <li>deliberately providing wrong information to users or developers</li>
367 <li>deliberately writing flawed documentation</li>
368 <li>deliberately corrupting documents</li>
369 <li>
370 deliberately go against the decisions made policy-wise or through a
371 consensus-model on the Gentoo Documentation mailinglist
372 </li>
373 <li>
374 not performing at all for a long time without informing the GDP, and without
375 replying to the Operational Manager's request for a status update
376 </li>
377 </ul>
378
379 <p>
380 will be reported to the <uri link="/proj/en/devrel/">Gentoo Developer
381 Relations</uri> project.
382 </p>
383
384 </body>
385 </section>
386 </chapter>
387
388 <chapter>
389 <title>Documentation Team Recruitment</title>
390 <section>
391 <title>Contributors, Authors, Translators</title>
392 <body>
393
394 <p>
395 Everyone interested in contributing documentation, editing existing
396 documentation, writing new documentation or translating documentation is
397 welcome to send their contributions. There are no rules or strings attached to
398 this. Just make sure you are subscribed to <mail>gentoo-doc@gentoo.org</mail>,
399 and you have fully read this policy and understand it.
400 </p>
401
402 </body>
403 </section>
404 <section>
405 <title>Recruitment Process</title>
406 <body>
407
408 <p>
409 The Documentation Project has a strict recruitment process outlined below.
410 This process can not be deviated from in any circumstance. We have opted for
411 this recruitment process to assure ourselves that the recruit is well informed
412 about the Gentoo Documentation Policy and the Gentoo Coding Style. It has proven
413 to be quite effective even though many contributors see it as a too large burden
414 to cross.
415 </p>
416
417 <p>
418 This recruitment process is meant only for requests to the Gentoo Documentation
419 Repository through CVS. Being listed as the maintainer or point of contact for
420 a certain document or range of documents is granted by a simple request to the
421 Operational Manager or Project Lead.
422 </p>
423
424 </body>
425 </section>
426 <section>
427 <title>Phase 1: Contributions</title>
428 <body>
429
430 <p>
431 No recruitment process starts without investigating the contributions done
432 already to the Gentoo Documentation Project. The number of contributions must be
433 large to assure a good knowledge of GuideXML, Coding Style and policy. The
434 contribution period must be large as well to inform the contributor about the
435 time-consuming position and pressure the application involves.
436 </p>
437
438 <p>
439 The number of contributions and period over which the contributions should be
440 made depends on the position which the contributor solicits for. Although it is
441 difficult to write down these measurements in numbers, the following table
442 should give a general overview. Final decision however lays in the hands of the
443 Operational Manager.
444 </p>
445
446 <table>
447 <tr>
448 <th>Position</th>
449 <th>Minimal Activity</th>
450 <th>Minimal Period</th>
451 </tr>
452 <tr>
453 <ti>Full-time Developer</ti>
454 <ti>2 updates per week</ti>
455 <ti>1 month</ti>
456 </tr>
457 <tr>
458 <ti>Part-time Developer</ti>
459 <ti>4 updates per month</ti>
460 <ti>1 month</ti>
461 </tr>
462 </table>
463
464 <p>
465 An update constitutes a non-trivial update to any documentation, translation or
466 otherwise, completely written by the contributor and committed after review by
467 any existing documentation developer. The period is fixed - increasing the
468 contributions does not decrease the period. Also, we don't average the
469 contributions over time to make sure the contributor doesn't give a contribution
470 burst, and then waits until the phase is over.
471 </p>
472
473 <p>
474 Without this phase, we can not know if the contributor understands what it
475 takes to be a documentation developer. The validation of this activity happens
476 through bugzilla reports.
477 </p>
478
479 <p>
480 Any request for CVS access that does not allow a development activity as written
481 down in the aforementioned table will not be taken into account.
482 </p>
483
484 <p>
485 If you feel that you have shown sufficient amount of contributions, contact
486 the Operational Manager of the Gentoo Documentation Project. He
487 will ask you for your coordinates and other information, and then arrange
488 for the next phase to be started.
489 </p>
490
491 </body>
492 </section>
493 <section>
494 <title>Phase 2: Start the Recruitment Process</title>
495 <body>
496
497 <p>
498 During this period, which is roughly the same as the aforementioned table,
499 submitted patches are not edited by a documentation developer anymore, but are
500 either committed as-is or refused. The recruit is also assigned to a full-time
501 documentation developer (the mentor) which will guide him through these last
502 phases.
503 </p>
504
505 <p>
506 The quality of the contributions are in this phase most important - every patch
507 that does not follow the Documentation Policy, Coding Style or other guideline
508 that affects the document is refused.
509 </p>
510
511 <p>
512 During this period, you:
513 </p>
514
515 <ul>
516 <li>
517 are advised to learn about Gentoo's inner workings.
518 This is required as you will be asked later on to answer Gentoo's <uri
519 link="/proj/en/devrel/quiz/staff-quiz.txt">Staffing Quiz</uri>.
520 </li>
521 <li>
522 will be asked to fill in the <uri
523 link="/proj/en/gdp/doc/doc-quiz.xml">Gentoo Documentation Project
524 Quiz</uri>. You need to successfully pass this entire quiz (all questions)
525 before you can continue with the next Phase.
526 </li>
527 </ul>
528
529 </body>
530 </section>
531 <section>
532 <title>Phase 3: Gentoo Recruitment</title>
533 <body>
534
535 <p>
536 When Phase 2 is finished, the Operational Manager will contact <uri
537 link="/proj/en/devrel/">Developer Relations</uri> and give a final "Go!" for the
538 Gentoo recruitment process after which you will be given a Gentoo e-mail
539 address and be appointed to one or more subprojects.
540 </p>
541
542 </body>
543 </section>
544 </chapter>
545 </guide>

  ViewVC Help
Powered by ViewVC 1.1.20