/[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.9 - (show annotations) (download) (as text)
Fri Jan 7 23:02:29 2005 UTC (9 years, 8 months ago) by neysx
Branch: MAIN
Changes since 1.8: +27 -39 lines
File MIME type: application/xml
Content change: date/version bumping of master handbook file is not required anymore whenever a part is updated.
Cosmetic changes: links/coding style

1 <?xml version='1.0' encoding="UTF-8"?>
2 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/proj/en/gdp/doc/doc-policy.xml,v 1.8 2004/12/28 17:20:15 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.10</version>
31 <date>2005-01-08</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 subscribed to 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.
154 </p>
155
156 <p>
157 Every member 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 he is online.
160 </p>
161
162 <p>
163 Depending on his responsibilities, he can have limited CVS
164 access to <c>cvs.gentoo.org</c>. CVS access can only be given to Gentoo
165 developers.
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 lead by a lead translator and perhaps a follow-up lead translator, who
177 both have CVS commit access. If for any reason the lead translator cannot
178 perform his or her duties, the follow-up lead translator is in charge. If
179 even this person is unavailable, the mentor(s) is/are in charge of the language.
180 </p>
181
182 <p>
183 If a translated document is contributed, but the language in itself is
184 not supported, the Gentoo Documentation Team will not publish it
185 officially. In this case the document will stay unlinked until an official
186 translation team of that language is formed.
187 </p>
188
189 <p>
190 When a language is officially supported, but the team doesn't have any
191 members or no one wants to take on the responsibilities of the lead
192 translator, all links to the documents will be removed from the site.
193 However, the documents will stay available in case the language becomes
194 officially supported again.
195 </p>
196
197 </body>
198 </section>
199 </chapter>
200
201 <chapter>
202 <title>Gentoo Documentation Guidelines</title>
203 <section>
204 <title>Legal Issues</title>
205 <body>
206
207 <p>
208 Every document published by the Gentoo Documentation Project must be
209 licensed by the <uri
210 link="http://creativecommons.org/licenses/by-sa/2.0/">Creative Commons
211 Attribution-ShareAlike License</uri>.
212 </p>
213
214 <p>
215 Every document must have the following tag inside its GuideXML
216 sourcecode between the <c>&lt;/abstract&gt;</c> and the <c>&lt;version&gt;</c>
217 tags:
218 </p>
219
220 <pre caption = "Licensing notice for the Gentoo Documentation">
221 &lt;/abstract&gt;
222 <i>
223 &lt;!-- The content of this document is licensed under the CC-BY-SA license --&gt;
224 &lt;!-- See http://creativecommons.org/licenses/by-sa/2.0 --&gt;
225 &lt;license/&gt;
226 </i>
227 &lt;version&gt;...&lt;/version&gt;
228 </pre>
229
230 </body>
231 </section>
232 <section>
233 <title>Bugs and Updates</title>
234 <body>
235
236 <p>
237 Every bug reported on <uri link="http://bugs.gentoo.org">bugs.gentoo.org</uri>
238 should be handled as fast as possible. If a bug cannot be handled
239 in a timely fashion, the reporter of that bug should be informed about
240 this using a comment on the bug and the bug should be registered in the
241 <uri link="/proj/en/gdp/doc/metadoc-guide.xml">metadoc.xml</uri> file, if
242 applicable. The tactical or operational manager can decide that a bug has a
243 higher priority and should be handled first before any other task the assingee
244 is responsible of.
245 </p>
246
247 <p>
248 Whenever a Gentoo Documentation Team member takes care of a bug, he or
249 she should assign the bug to herself/himself, but make sure that
250 <c>docs-team@gentoo.org</c> is on the Cc-list. Unless with the consent
251 of the operational manager, a bug may not be taken away from another
252 Gentoo Documentation Team member without their approval.
253 </p>
254
255 </body>
256 </section>
257 <section>
258 <title>Document Development</title>
259 <body>
260
261 <p>
262 Every document the Gentoo Documentation Team develops can be developed as the
263 related parties see fit. However, when the document is finished, it should be
264 transformed into <uri link="/doc/en/xml-guide.xml">GuideXML</uri> and put
265 available on the Gentoo CVS infrastructure. It must also be registered in the
266 <uri link="/proj/en/gdp/doc/metadoc-guide.xml">metadoc.xml</uri> file if
267 applicable.
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 All changes in XML formatting should lead to version (and date) bumps only in
289 case the layout of the document changes.
290 </p>
291
292 <p>
293 Whether or not to increment the major version number instead of minor version
294 number or other is up to the editor.
295 </p>
296
297 <p>
298 Every update of a translation should copy the new version information
299 verbatim from the master English document so fully synchronised
300 translations have the same version information.
301 </p>
302
303 </body>
304 </section>
305 <section>
306 <title>Reviewing and Committing</title>
307 <body>
308
309 <p>
310 To keep a high-pace development cycle of the documentation, technical or
311 intrusive changes to documents can be propagated immediately to the document
312 <e>if</e> the editor is 100% confident his changes are correct and working. If
313 you are not 100% confident (for instance because a user has told you how to fix
314 it but you cannot verify yourself), have the change reviewed by a Gentoo
315 Developer that can verify the change.
316 </p>
317
318 <p>
319 High volume, technical or intrusive changes must be accompanied by a bugreport
320 on <uri>http://bugs.gentoo.org</uri>. This bugnumber <e>must</e> be mentioned in
321 the CVS log to allow backtracing of changes.
322 </p>
323
324 <p>
325 If a bugfix consists out of both content as internal coding changes,
326 both changes must be committed seperately so that translators can easily
327 view the important changes (content) and ignore the coding changes.
328 </p>
329
330 <p>
331 In case of a translation, the lead translator of the language is
332 responsible for the document. Only he may commit the document to CVS
333 unless he is currently "in training", in which case his or her
334 mentor should commit it.
335 </p>
336
337 </body>
338 </section>
339 <section>
340 <title>Sanctions</title>
341 <body>
342
343 <p>
344 Although this has never been necessary, it is still important to list this in
345 the policy - even though it is hateful. Anyway, documentation developers that
346 misuse their position by
347 </p>
348
349 <ul>
350 <li>deliberately providing wrong information to users or developers</li>
351 <li>deliberately writing flawed documentation</li>
352 <li>deliberately corrupting documents</li>
353 <li>
354 deliberately go against the decisions made policy-wise or through a
355 consensus-model on the Gentoo Documentation mailinglist
356 </li>
357 <li>
358 not performing at all for a long time without informing the GDP and without
359 replying to the operational manager's request for a status update
360 </li>
361 </ul>
362
363 <p>
364 will be reported to the <uri link="/proj/en/devrel/">Gentoo Developer
365 Relations</uri> project.
366 </p>
367
368 </body>
369 </section>
370 </chapter>
371
372 <chapter>
373 <title>Documentation Team Recruitement</title>
374 <section>
375 <title>Contributors, Authors, Translators</title>
376 <body>
377
378 <p>
379 Everyone interested in contributing documentation, editing existing
380 documentation, writing new documentation or translating documentation is
381 welcome to join the team. There are no rules or strings attached to
382 this. Just make sure you are subscribed to <c>gentoo-doc@gentoo.org</c>
383 and you have fully read this policy and understand it.
384 </p>
385
386 </body>
387 </section>
388 <section>
389 <title>Gentoo Documentation Developer</title>
390 <body>
391
392 <p>
393 As a Gentoo documentation developer should know everything in the <uri
394 link="/proj/en/devrel/handbook/handbook.xml?part=3&amp;chap=1">Gentoo Ebuild
395 Policy</uri> even though you're not submitting ebuilds. This is all needed to
396 ensure our userbase that no Gentoo developer gives wrong information about
397 critical things.
398 </p>
399
400 <p>
401 Contact the operational manager of the Gentoo Documentation Project. He
402 will ask you for your coordinates and other information and then arrange
403 a mentor for you who will guide you through the first days or weeks as
404 developer.
405 </p>
406
407 <p>
408 You will be given a Gentoo e-mail address and be appointed to one or
409 more subprojects. During the initial days or weeks, you should ask your
410 mentor as much as possible, preferably have him double-check everything
411 you do. If your function requires CVS access, you will only receive it
412 when your mentor deems it appropriate. Until then, your mentor is in
413 charge of the CVS commits.
414 </p>
415
416 </body>
417 </section>
418 <section>
419 <title>(Follow-Up) Lead Translator</title>
420 <body>
421
422 <p>
423 Becoming a (follow-up) lead translator shouldn't be held lightly. You are
424 responsible for every translated document and final reviewing. The lead
425 translator will make certain that the translated documents are
426 grammatically and syntactically perfect.
427 </p>
428
429 <p>
430 In order to become a Gentoo (follow-up) lead translator you must be a Gentoo
431 developer.
432 </p>
433
434 <p>
435 During your "training" period you are a (follow-up) lead translator and
436 should act upon it. All guidelines regarding (follow-up) lead translators
437 apply.
438 </p>
439
440 </body>
441 </section>
442 </chapter>
443 </guide>

  ViewVC Help
Powered by ViewVC 1.1.20