/[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.6 - (show annotations) (download) (as text)
Tue Nov 9 08:30:19 2004 UTC (9 years, 8 months ago) by swift
Branch: MAIN
Changes since 1.5: +6 -6 lines
File MIME type: application/xml
Change reference to 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.5 2004/09/17 11:34:53 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.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.7</version>
31 <date>November 09, 2004</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
82 manager as required by the
83 <uri link="http://www.gentoo.org/doc/en/management-structure.xml">Gentoo
84 Management Structure</uri>. This document also describes the responsibilities of
85 the strategic manager with respect to Gentoo Linux.
86 </p>
87
88 <p>
89 For day-to-day managerial tasks the Gentoo Documentation Project has an
90 operational manager. This person keeps track of all
91 documentation-related tasks that are more short-term. The operational
92 manager and strategic manager can be one and the same if the strategic
93 manager wishes so.
94 </p>
95
96 <p>
97 Currently these positions are taken by the following people:
98 </p>
99
100 <table>
101 <tr>
102 <th>Position</th>
103 <th>Developer Name</th>
104 <th>Developer Nick</th>
105 </tr>
106 <tr>
107 <ti>Strategic Manager</ti>
108 <ti>Sven Vermeulen</ti>
109 <ti><mail link="swift@gentoo.org">swift</mail></ti>
110 </tr>
111 <tr>
112 <ti>Operational Manager</ti>
113 <ti>Xavier Neys</ti>
114 <ti><mail link="neysx@gentoo.org">neysx</mail></ti>
115 </tr>
116 </table>
117
118 <p>
119 Every subproject has a strategic manager of its own. he can
120 have an operational manager if he deems appropriate. His
121 responsibilities to the Gentoo Documentation Project are the same as are
122 listed on the <uri
123 link="http://www.gentoo.org/doc/en/management-structure.xml#doc_chap1_sect5">Gentoo
124 Management Structure</uri>.
125 </p>
126
127 <p>
128 The subprojects of the Gentoo Documentation Team together with their
129 respective strategic managers are listed on the <uri
130 link="http://www.gentoo.org/proj/en/gdp">GDP Website</uri>.
131 </p>
132
133 <p>
134 The decision on adding subprojects is in hands of the strategic manager.
135 </p>
136
137 </body>
138 </section>
139 <section>
140 <title>Documentation Project Team Members</title>
141 <body>
142
143 <p>
144 Every member of the Gentoo Documentation Project must be subscribed to
145 the <mail link="gentoo-doc-subscribe@gentoo.org">gentoo-doc@gentoo.org</mail>
146 mailing list. This mailing list will be used to discuss all
147 documentation-related issues. This mailing list is open to all interested
148 parties, developer or not.
149 </p>
150
151 <p>
152 Every member of the Gentoo Documentation Project must be subscribed to
153 the <mail link="docs-team@gentoo.org">docs-team@gentoo.org</mail> alias.
154 This alias is <e>only</e> used by <uri
155 link="http://bugs.gentoo.org">bugs.gentoo.org</uri>
156 to inform the documentation team about bugs regarding the Gentoo
157 Documentation.
158 </p>
159
160 <p>
161 Every member of the Gentoo Documentation Team should be available at
162 <c>#gentoo-doc</c> on <uri link="http://www.freenode.net">irc.freenode.net</uri>
163 whenever he is online.
164 </p>
165
166 <p>
167 Depending on his responsibilities, he can have limited CVS
168 access to <c>cvs.gentoo.org</c>. CVS access can only be given to Gentoo
169 developers.
170 </p>
171
172 </body>
173 </section>
174 <section>
175 <title>Documentation Translation Teams</title>
176 <body>
177
178 <p>
179 Every language should be backed up by an official translation team. This
180 team is lead by a lead translator and perhaps a follow-up lead translator, who
181 both have CVS commit access. If for any reason the lead translator cannot
182 perform his or her duties, the follow-up lead translator is in charge. If
183 even this person is unavailable, the mentor(s) is/are in charge of the language.
184 </p>
185
186 <p>
187 If a translated document is contributed, but the language in itself is
188 not supported, the Gentoo Documentation Team will not publish it
189 officially. In this case the document will stay unlinked until an official
190 translation team of that language is formed.
191 </p>
192
193 <p>
194 When a language is officially supported, but the team doesn't have any
195 members or no one wants to take on the responsibilities of the lead
196 translator, all links to the documents will be removed from the site.
197 However, the documents will stay available in case the language becomes
198 officially supported again.
199 </p>
200
201 </body>
202 </section>
203 </chapter>
204
205 <chapter>
206 <title>Gentoo Documentation Guidelines</title>
207 <section>
208 <title>Legal Issues</title>
209 <body>
210
211 <p>
212 Every document published by the Gentoo Documentation Project must be
213 licensed by the <uri
214 link="http://creativecommons.org/licenses/by-sa/2.0/">Creative Commons
215 Attribution-ShareAlike License</uri>.
216 </p>
217
218 <p>
219 Every document must have the following tag inside its GuideXML
220 sourcecode between the <c>&lt;/abstract&gt;</c> and the <c>&lt;version&gt;</c>
221 tags:
222 </p>
223
224 <pre caption = "Licensing notice for the Gentoo Documentation">
225 &lt;/abstract&gt;
226 <i>
227 &lt;!-- The content of this document is licensed under the CC-BY-SA license --&gt;
228 &lt;!-- See http://creativecommons.org/licenses/by-sa/2.0 --&gt;
229 &lt;license/&gt;
230 </i>
231 &lt;version&gt;...&lt;/version&gt;
232 </pre>
233
234 </body>
235 </section>
236 <section>
237 <title>Bugs and Updates</title>
238 <body>
239
240 <p>
241 Every bug reported on <uri link="http://bugs.gentoo.org">bugs.gentoo.org</uri>
242 should be handled as fast as possible. If a bug cannot be handled
243 in a timely fashion, the reporter of that bug should be informed about
244 this using a comment on the bug. The tactical or operational manager can
245 decide that a bug has a higher priority and should be handled first before any
246 other task the assingee is responsible of.
247 </p>
248
249 <p>
250 Whenever a Gentoo Documentation Team member takes care of a bug, he or
251 she should assign the bug to herself/himself, but make sure that
252 <c>docs-team@gentoo.org</c> is on the Cc-list. Unless with the consent
253 of the operational manager, a bug may not be taken away from another
254 Gentoo Documentation Team member without their approval.
255 </p>
256
257 </body>
258 </section>
259 <section>
260 <title>Document Development</title>
261 <body>
262
263 <p>
264 Every document the Gentoo Documentation Team develops can be developed
265 as the related parties see fit. However, when the document is finished,
266 it should be transformed into <uri
267 link="http://www.gentoo.org/doc/en/xml-guide.xml">GuideXML</uri>.
268 </p>
269
270 <p>
271 When a new document is started or a big change is needed, a bug should be filed
272 at <uri link="http://bugs.gentoo.org">bugs.gentoo.org</uri>
273 concerning the development of this document. If there is already a bug
274 in the database that requests a change to the documentation, a new bug
275 does not have to be filed. Grammatical, syntactical or small changes
276 do not require a bug to be filed on <uri
277 link="http://bugs.gentoo.org">bugs.gentoo.org</uri> as well.
278 </p>
279
280 <p>
281 All changes in contents of the document, except for typo fixes in text
282 itself or in the comments to code listings, should lead to version
283 number (and date) increase. Note that the change of a Code Listings should
284 definitely cause an increase of the version number and date.
285 </p>
286
287 <p>
288 When updating a handbook-related file (such as the various
289 <path>hb-*</path> files) you must bump the parental
290 <path>handbook-&lt;arch&gt;.xml</path> file as well and commit all files at
291 once (which also means an identical commit message).
292 </p>
293
294 <p>
295 All changes in XML formatting should lead to version (and date) bumps only in
296 case the layout of the document changes.
297 </p>
298
299 <p>
300 Whether or not to increment the major version number instead of minor version
301 number or other is up to the editor.
302 </p>
303
304 <p>
305 Every update of a translation should copy the new version information
306 verbatim from the master English document so fully synchronised
307 translations have the same version information.
308 </p>
309
310 </body>
311 </section>
312 <section>
313 <title>Reviewing and Committing</title>
314 <body>
315
316 <p>
317 To keep a high-pace development cycle of the documentation, technical or
318 intrusive changes to documents can be propagated immediately to the document
319 <e>if</e> the editor is 100% confident his changes are correct and working. If
320 you are not 100% confident (for instance because a user has told you how to fix
321 it but you cannot verify yourself), have the change reviewed by a Gentoo
322 Developer that can verify the change.
323 </p>
324
325 <p>
326 High volume, technical or intrusive changes must be accompanied by a bugreport
327 on <uri>http://bugs.gentoo.org</uri>. This bugnumber <e>must</e> be mentioned in
328 the CVS log to allow backtracing of changes.
329 </p>
330
331 <p>
332 If a bugfix consists out of both content as internal coding changes,
333 both changes must be committed seperately so that translators can easily
334 view the important changes (content) and ignore the coding changes.
335 </p>
336
337 <p>
338 In case of a translation, the lead translator of the language is
339 responsible for the document. Only he may commit the document to CVS
340 unless he is currently "in training", in which case his or her
341 mentor should commit it.
342 </p>
343
344 </body>
345 </section>
346 <section>
347 <title>Sanctions</title>
348 <body>
349
350 <p>
351 Although this has never been necessary, it is still important to list this in
352 the policy - even though it is hateful. Anyway, documentation developers that
353 misuse their position by
354 </p>
355
356 <ul>
357 <li>deliberately providing wrong information to users or developers</li>
358 <li>deliberately writing flawed documentation</li>
359 <li>deliberately corrupting documents</li>
360 <li>
361 deliberately go against the decisions made policy-wise or through a
362 consensus-model on the Gentoo Documentation mailinglist
363 </li>
364 <li>
365 not performing at all for a long time without informing the GDP and without
366 replying to the operational manager's request for a status update
367 </li>
368 </ul>
369
370 <p>
371 will be reported to the <uri link="/proj/en/devrel">Gentoo Developer
372 Relations</uri> project.
373 </p>
374
375 </body>
376 </section>
377 </chapter>
378
379 <chapter>
380 <title>Documentation Team Recruitement</title>
381 <section>
382 <title>Contributors, Authors, Translators</title>
383 <body>
384
385 <p>
386 Everyone interested in contributing documentation, editing existing
387 documentation, writing new documentation or translating documentation is
388 welcome to join the team. There are no rules or strings attached to
389 this. Just make sure you are subscribed to <c>gentoo-doc@gentoo.org</c>
390 and you have fully read this policy and understand it.
391 </p>
392
393 </body>
394 </section>
395 <section>
396 <title>Gentoo Documentation Developer</title>
397 <body>
398
399 <p>
400 As a Gentoo documentation developer should know everything in the <uri
401 link="/proj/en/devrel/handbook/handbook.xml?part=3&amp;chap=1">Gentoo Ebuild
402 Policy</uri> even though you're not submitting ebuilds. You should also have
403 read the <uri link="http://www.gentoo.org/doc/en/gentoo-release-policy.xml">Gentoo
404 Release Policy</uri> and <uri
405 link="http://www.gentoo.org/doc/en/management-structure.xml">Gentoo Management
406 Structure</uri>. This is all needed to ensure our userbase that no Gentoo
407 developer gives wrong information about critical things.
408 </p>
409
410 <p>
411 Contact the operational manager of the Gentoo Documentation Project. He
412 will ask you for your coordinates and other information and then arrange
413 a mentor for you who will guide you through the first days or weeks as
414 developer.
415 </p>
416
417 <p>
418 You will be given a Gentoo e-mail address and be appointed to one or
419 more subprojects. During the initial days or weeks, you should ask your
420 mentor as much as possible, preferably have him double-check everything
421 you do. If your function requires CVS access, you will only receive it
422 when your mentor deems it appropriate. Until then, your mentor is in
423 charge of the CVS commits.
424 </p>
425
426 </body>
427 </section>
428 <section>
429 <title>(Follow-Up) Lead Translator</title>
430 <body>
431
432 <p>
433 Becoming a (follow-up) lead translator shouldn't be held lightly. You are
434 responsible for every translated document and final reviewing. The lead
435 translator will make certain that the translated documents are
436 grammatically and syntactically perfect.
437 </p>
438
439 <p>
440 In order to become a Gentoo (follow-up) lead translator you must be a Gentoo
441 developer.
442 </p>
443
444 <p>
445 During your "training" period you are a (follow-up) lead translator and
446 should act upon it. All guidelines regarding (follow-up) lead translators
447 apply.
448 </p>
449
450 </body>
451 </section>
452 </chapter>
453 </guide>

  ViewVC Help
Powered by ViewVC 1.1.20