/[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.8 - (show annotations) (download) (as text)
Tue Dec 28 17:20:15 2004 UTC (10 years ago) by swift
Branch: MAIN
Changes since 1.7: +12 -7 lines
File MIME type: application/xml
Add metadoc.xml file usage

1 <?xml version='1.0' encoding="UTF-8"?>
2 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/proj/en/gdp/doc/doc-policy.xml,v 1.7 2004/11/09 08:35:47 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.9</version>
31 <date>2004-12-28</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 and the bug should be registered in the
245 <uri link="/proj/en/gdp/doc/metadoc-guide.xml">metadoc.xml</uri> file, if
246 applicable. The tactical or operational manager can decide that a bug has a
247 higher priority and should be handled first before any other task the assingee
248 is responsible of.
249 </p>
250
251 <p>
252 Whenever a Gentoo Documentation Team member takes care of a bug, he or
253 she should assign the bug to herself/himself, but make sure that
254 <c>docs-team@gentoo.org</c> is on the Cc-list. Unless with the consent
255 of the operational manager, a bug may not be taken away from another
256 Gentoo Documentation Team member without their approval.
257 </p>
258
259 </body>
260 </section>
261 <section>
262 <title>Document Development</title>
263 <body>
264
265 <p>
266 Every document the Gentoo Documentation Team develops can be developed
267 as the related parties see fit. However, when the document is finished,
268 it should be transformed into <uri
269 link="http://www.gentoo.org/doc/en/xml-guide.xml">GuideXML</uri> and put
270 available on the Gentoo CVS infrastructure. It must also be registered in the
271 <uri link="/proj/en/gdp/doc/metadoc-guide.xml">metadoc.xml</uri> file if
272 applicable.
273 </p>
274
275 <p>
276 When a new document is started or a big change is needed, a bug should be filed
277 at <uri link="http://bugs.gentoo.org">bugs.gentoo.org</uri>
278 concerning the development of this document. If there is already a bug
279 in the database that requests a change to the documentation, a new bug
280 does not have to be filed. Grammatical, syntactical or small changes
281 do not require a bug to be filed on <uri
282 link="http://bugs.gentoo.org">bugs.gentoo.org</uri> as well.
283 </p>
284
285 <p>
286 All changes in contents of the document, except for typo fixes in text
287 itself or in the comments to code listings, should lead to version
288 number (and date) increase. Note that the change of a Code Listings should
289 definitely cause an increase of the version number and date.
290 </p>
291
292 <p>
293 When updating a handbook-related file (such as the various
294 <path>hb-*</path> files) you must bump the parental
295 <path>handbook-&lt;arch&gt;.xml</path> file as well and commit all files at
296 once (which also means an identical commit message).
297 </p>
298
299 <p>
300 All changes in XML formatting should lead to version (and date) bumps only in
301 case the layout of the document changes.
302 </p>
303
304 <p>
305 Whether or not to increment the major version number instead of minor version
306 number or other is up to the editor.
307 </p>
308
309 <p>
310 Every update of a translation should copy the new version information
311 verbatim from the master English document so fully synchronised
312 translations have the same version information.
313 </p>
314
315 </body>
316 </section>
317 <section>
318 <title>Reviewing and Committing</title>
319 <body>
320
321 <p>
322 To keep a high-pace development cycle of the documentation, technical or
323 intrusive changes to documents can be propagated immediately to the document
324 <e>if</e> the editor is 100% confident his changes are correct and working. If
325 you are not 100% confident (for instance because a user has told you how to fix
326 it but you cannot verify yourself), have the change reviewed by a Gentoo
327 Developer that can verify the change.
328 </p>
329
330 <p>
331 High volume, technical or intrusive changes must be accompanied by a bugreport
332 on <uri>http://bugs.gentoo.org</uri>. This bugnumber <e>must</e> be mentioned in
333 the CVS log to allow backtracing of changes.
334 </p>
335
336 <p>
337 If a bugfix consists out of both content as internal coding changes,
338 both changes must be committed seperately so that translators can easily
339 view the important changes (content) and ignore the coding changes.
340 </p>
341
342 <p>
343 In case of a translation, the lead translator of the language is
344 responsible for the document. Only he may commit the document to CVS
345 unless he is currently "in training", in which case his or her
346 mentor should commit it.
347 </p>
348
349 </body>
350 </section>
351 <section>
352 <title>Sanctions</title>
353 <body>
354
355 <p>
356 Although this has never been necessary, it is still important to list this in
357 the policy - even though it is hateful. Anyway, documentation developers that
358 misuse their position by
359 </p>
360
361 <ul>
362 <li>deliberately providing wrong information to users or developers</li>
363 <li>deliberately writing flawed documentation</li>
364 <li>deliberately corrupting documents</li>
365 <li>
366 deliberately go against the decisions made policy-wise or through a
367 consensus-model on the Gentoo Documentation mailinglist
368 </li>
369 <li>
370 not performing at all for a long time without informing the GDP and without
371 replying to the operational manager's request for a status update
372 </li>
373 </ul>
374
375 <p>
376 will be reported to the <uri link="/proj/en/devrel">Gentoo Developer
377 Relations</uri> project.
378 </p>
379
380 </body>
381 </section>
382 </chapter>
383
384 <chapter>
385 <title>Documentation Team Recruitement</title>
386 <section>
387 <title>Contributors, Authors, Translators</title>
388 <body>
389
390 <p>
391 Everyone interested in contributing documentation, editing existing
392 documentation, writing new documentation or translating documentation is
393 welcome to join the team. There are no rules or strings attached to
394 this. Just make sure you are subscribed to <c>gentoo-doc@gentoo.org</c>
395 and you have fully read this policy and understand it.
396 </p>
397
398 </body>
399 </section>
400 <section>
401 <title>Gentoo Documentation Developer</title>
402 <body>
403
404 <p>
405 As a Gentoo documentation developer should know everything in the <uri
406 link="/proj/en/devrel/handbook/handbook.xml?part=3&amp;chap=1">Gentoo Ebuild
407 Policy</uri> even though you're not submitting ebuilds. This is all needed to
408 ensure our userbase that no Gentoo developer gives wrong information about
409 critical things.
410 </p>
411
412 <p>
413 Contact the operational manager of the Gentoo Documentation Project. He
414 will ask you for your coordinates and other information and then arrange
415 a mentor for you who will guide you through the first days or weeks as
416 developer.
417 </p>
418
419 <p>
420 You will be given a Gentoo e-mail address and be appointed to one or
421 more subprojects. During the initial days or weeks, you should ask your
422 mentor as much as possible, preferably have him double-check everything
423 you do. If your function requires CVS access, you will only receive it
424 when your mentor deems it appropriate. Until then, your mentor is in
425 charge of the CVS commits.
426 </p>
427
428 </body>
429 </section>
430 <section>
431 <title>(Follow-Up) Lead Translator</title>
432 <body>
433
434 <p>
435 Becoming a (follow-up) lead translator shouldn't be held lightly. You are
436 responsible for every translated document and final reviewing. The lead
437 translator will make certain that the translated documents are
438 grammatically and syntactically perfect.
439 </p>
440
441 <p>
442 In order to become a Gentoo (follow-up) lead translator you must be a Gentoo
443 developer.
444 </p>
445
446 <p>
447 During your "training" period you are a (follow-up) lead translator and
448 should act upon it. All guidelines regarding (follow-up) lead translators
449 apply.
450 </p>
451
452 </body>
453 </section>
454 </chapter>
455 </guide>

  ViewVC Help
Powered by ViewVC 1.1.20