/[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.17 - (show annotations) (download) (as text)
Sat Nov 26 13:02:12 2005 UTC (8 years, 4 months ago) by jkt
Branch: MAIN
Changes since 1.16: +4 -4 lines
File MIME type: application/xml
Added missing CVS $Header$

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

  ViewVC Help
Powered by ViewVC 1.1.20