/[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.20 - (show annotations) (download) (as text)
Thu Dec 22 22:24:11 2005 UTC (8 years, 8 months ago) by neysx
Branch: MAIN
Changes since 1.19: +5 -3 lines
File MIME type: application/xml
#116388 /doc/en/management-structure.xml is a dodo

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

  ViewVC Help
Powered by ViewVC 1.1.20