/[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.19 - (show annotations) (download) (as text)
Sat Nov 26 13:18:07 2005 UTC (8 years, 8 months ago) by neysx
Branch: MAIN
Changes since 1.18: +4 -4 lines
File MIME type: application/xml
jkt left a "2.0"

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

  ViewVC Help
Powered by ViewVC 1.1.20