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></abstract></c> and the <c><version></c> |
221 |
tags: |
222 |
</p> |
223 |
|
224 |
<pre caption = "Licensing notice for the Gentoo Documentation"> |
225 |
</abstract> |
226 |
<i> |
227 |
<!-- The content of this document is licensed under the CC-BY-SA license --> |
228 |
<!-- See http://creativecommons.org/licenses/by-sa/2.0 --> |
229 |
<license/> |
230 |
</i> |
231 |
<version>...</version> |
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-<arch>.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&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> |