/[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.22 - (show annotations) (download) (as text)
Thu Sep 28 13:21:22 2006 UTC (8 years, 9 months ago) by neysx
Branch: MAIN
Changes since 1.21: +9 -6 lines
File MIME type: application/xml
We already miss swift

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