/[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.11 - (show annotations) (download) (as text)
Sat May 7 19:06:52 2005 UTC (9 years, 2 months ago) by swift
Branch: MAIN
Changes since 1.10: +122 -33 lines
File MIME type: application/xml
Update on GDP policy

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

  ViewVC Help
Powered by ViewVC 1.1.20