/[gentoo]/xml/htdocs/proj/en/gdp/doc/doc-policy.xml
Gentoo

Diff of /xml/htdocs/proj/en/gdp/doc/doc-policy.xml

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

Revision 1.2 Revision 1.3
1<?xml version='1.0' encoding="UTF-8"?> 1<?xml version='1.0' encoding="UTF-8"?>
2<?xml-stylesheet href="/xsl/guide.xsl" type="text/xsl"?> 2<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/proj/en/gdp/doc/doc-policy.xml,v 1.3 2004/08/26 16:16:04 swift Exp $ -->
3
3<!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> 4<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
4 5
5<guide link="/proj/en/gdp/doc/doc-developer-guide.xml"> 6<guide link="/doc/en/doc-policy.xml">
6 7
7<title>Gentoo Linux Documentation Policy</title> 8<title>Gentoo Linux Documentation Policy</title>
8<author title="Author"><mail link="zhen@gentoo.org">John P. Davis</mail></author> 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
9<abstract> 22<abstract>
10 This guide explains the current Gentoo Documentation Policy. 23This document contains the Gentoo Documentation Policy, which is the
24base document which all Gentoo Documentation developers and
25Contributers should know and exercise.
11</abstract> 26</abstract>
12 27
28<license/>
29
13<version>2.1.1</version> 30<version>3.6</version>
14<date>1 April 2003</date> 31<date>August 14, 2004</date>
15 32
16<chapter> 33<chapter>
17 <title>Introduction</title> 34<title>Introduction</title>
18 <section> 35<section>
19 <title>Introduction</title> 36<title>Introduction</title>
20 <body> 37<body>
21 38
39<p>
22 <p><B>The Gentoo Linux Documentation team aspires to create exceptionally professional 40The Gentoo Linux Documentation team aspires to create exceptionally
23 documentation that is immediately clear and concise to the end user</B>. In order to 41professional documentation that is immediately clear and concise to the
24 fulfill this goal, we have very specific rules and guidelines that <e>all</e> 42end user. In order to fulfill this goal, we have very specific rules and
25 documentation must go through before it is published on our website, or otherwise. 43guidelines that <e>all</e> documentation must go through before it is
26 </p> 44published on our website, or otherwise.
27 45</p>
46
28 </body> 47</body>
29 </section> 48</section>
30
31 <section> 49<section>
32 <title>Covered Topics</title> 50<title>Covered Topics</title>
33 <body> 51<body>
34 52
53<p>
35 <p>This policy will cover these topics: </p> 54This policy will cover these topics:
36 <ul> 55</p>
56
57<ul>
37 <li>Documentation Team Organization</li> 58<li>Documentation Project Team Organization</li>
38 <li>English Developer Guidelines </li> 59<li>Documentation Guidelines</li>
39 <li>Translator Guidelines</li> 60<li>Documentation Team Recruitement</li>
40 <li>Contact Lists </li>
41 </ul> 61</ul>
42 62
43 </body> 63</body>
44 </section> 64</section>
45
46 <section>
47 <title>Preliminaries</title>
48 <body>
49 <p>Before continuing, it is expected that all documentation developers be subscribed to
50 the <i>gentoo-doc@gentoo.org</i> mailinglist, and that they are readily available in
51 <i>#gentoo-doc</i> at all times.
52 </p>
53
54 <p>Additionally, some functional definitions are needed in order to specifically outline
55 the duties and responsibilities of the documentation team. </p>
56
57 <p><b>Official Gentoo Linux Documentation</b> is simply defined as any documentation
58 that is released by Gentoo Linux for consumption by the end user. The only exceptions to
59 this are the Gentoo Weekly Newsletter, and the <i>gentoo.org</i> website, which
60 are maintained by their own respective teams. </p>
61
62 <p>Gentoo Linux Documentation can be separated into two categories, critical and
63 non-critical documentation. </p>
64
65 <p><b>Critical Documentation</b> is defined as any documentation that is <e>directly</e>
66 involved with the installation and base configuration of any Gentoo Linux system.
67 To date, our critical documents are: </p>
68
69 <ul>
70 <li>All of the Gentoo Linux Installation Guides</li>
71 <li>The Desktop Configuration Guide</li>
72 <li>The official Gentoo Linux FAQ</li>
73 <li>The Gentoo Linux Security Guide</li>
74 <li>Any Portage Documentation</li>
75 </ul>
76
77 <p><b>Non-critical</b> documentation includes all documentation not specifically defined
78 as Critical Documentation. </p>
79
80 </body>
81 </section>
82 </chapter> 65</chapter>
83 66
84<chapter> 67<chapter>
85 <title>Documentation Team Organization</title> 68<title>Documentation Project Team Organization</title>
86 <section> 69<section>
87 <title>Organization</title> 70<title>Organization</title>
88 <body> 71<body>
89 <p>The Gentoo Linux Documentation team is split into three teams that operate
90 in complete cooperation with eachother. The Documentation team is divided into
91 these three categories:
92 </p>
93 72
94 <p><b>Technical Writers: </b>The technical writers' function is to completely 73<p>
95 document every aspect of Gentoo Linux. The writers will periodically be given 74The Gentoo Documentation Project Team is split into several smaller teams
96 assignments by the Senior Developers, and those assignments are to take precedence 75that operate in complete cooperation with each other. Each smaller team
97 over any other Gentoo Linux development work. Although the writers' work is 76represents an active development team of a Gentoo Documentation
98 ultimately proofed by the <b>Editing Team</b>, the writers <e>will still</e> 77Subproject.
99 proof their own work before submitting it to the <i>gentoo-docs-review@gentoo.org</i> 78</p>
100 mailing list and the <b>Editing Team</b> All technical writers must be subscribed to the
101 <i>gentoo-docs-review@gentoo.org</i> mailing list.</p>
102 79
103 <p><b>Editors/ Proofreaders: </b>The editors are in charge of editing and proofing 80<p>
104 all changes to the Gentoo Linux Documentation. No change can be made unless it is 81The Gentoo Documentation Project is strategically lead by a top-level
105 verified to be grammatically and syntactically correct by an Editor. The Editors 82manager as required by the
106 must make absolutely sure that <e>all</e> documentation going live on the website 83<uri link="http://www.gentoo.org/doc/en/management-structure.xml">Gentoo
107 is as professional and grammatically correct as possible. All Editors must 84Management Structure</uri>. This document also describes the responsibilities of
108 be subscribed to the <i>gentoo-docs-review@gentoo.org</i> mailing list.</p> 85the strategic manager with respect to Gentoo Linux.
86</p>
109 87
110 <p><b>Translators: </b>Due to the special nature of translations, the translators 88<p>
111 are broken into their own team. Each language will have a lead Developer which will 89For day-to-day managerial tasks the Gentoo Documentation Project has an
112 serve as the Editor and CVS publisher. Once the lead translator has deemed that 90operational manager. This person keeps track of all
113 a translation is ready to go live on the documentation index page, they may add it. 91documentation-related tasks that are more short-term. The operational
114 After the translation is added, a notice must be sent to the <i>gentoo-docs-review@gentoo.org</i> 92manager and strategic manager can be one and the same if the strategic
115 mailing list.</p> 93manager wishes so.
94</p>
95
96<p>
97Currently 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>
119Every subproject has a strategic manager of its own. He or she can
120have an operational manager if he or she deems appropriate. His
121responsibilities to the Gentoo Documentation Project are the same as are
122listed on the <uri
123link="http://www.gentoo.org/doc/en/management-structure.xml#doc_chap1_sect5">Gentoo
124Management Structure</uri>.
125</p>
126
127<p>
128The subprojects of the Gentoo Documentation Team together with their
129respective strategic managers are listed on the <uri
130link="http://www.gentoo.org/proj/en/gdp">GDP Website</uri>.
131</p>
132
133<p>
134The decision on adding subprojects is in hands of the strategic manager.
135</p>
136
116 </body> 137</body>
117 </section> 138</section>
139<section>
140<title>Documentation Project Team Members</title>
141<body>
142
143<p>
144Every member of the Gentoo Documentation Project must be subscribed to
145the <mail link="gentoo-doc-subscribe@gentoo.org">gentoo-doc@gentoo.org</mail>
146mailing list. This mailing list will be used to discuss all
147documentation-related issues. This mailing list is open to all interested
148parties, developer or not.
149</p>
150
151<p>
152Every member of the Gentoo Documentation Project must be subscribed to
153the <mail link="docs-team@gentoo.org">docs-team@gentoo.org</mail> alias.
154This alias is <e>only</e> used by <uri
155link="http://bugs.gentoo.org">bugs.gentoo.org</uri>
156to inform the documentation team about bugs regarding the Gentoo
157Documentation.
158</p>
159
160<p>
161Every 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>
163whenever he or she is online.
164</p>
165
166<p>
167Depending on her/his responsibilities, he or she can have limited CVS
168access to <c>cvs.gentoo.org</c>. CVS access can only be given to Gentoo
169developers.
170</p>
171
172</body>
173</section>
174<section>
175<title>Documentation Translation Teams</title>
176<body>
177
178<p>
179Every language should be backed up by an official translation team. This
180team is lead by a lead translator and perhaps a follow-up lead translator, who
181both have CVS commit access. If for any reason the lead translator cannot
182perform his or her duties, the follow-up lead translator is in charge. If
183even this person is unavailable, the mentor(s) is/are in charge of the language.
184</p>
185
186<p>
187If a translated document is contributed, but the language in itself is
188not supported, the Gentoo Documentation Team will not publish it
189officially. In this case the document will stay unlinked until an official
190translation team of that language is formed.
191</p>
192
193<p>
194When a language is officially supported, but the team doesn't have any
195members or no one wants to take on the responsibilities of the lead
196translator, all links to the documents will be removed from the site.
197However, the documents will stay available in case the language becomes
198officially supported again.
199</p>
200
201</body>
202</section>
118</chapter> 203</chapter>
119 204
120<chapter> 205<chapter>
121 <title>English Developer Guidelines</title> 206<title>Gentoo Documentation Guidelines</title>
122 <section> 207<section>
123 <title>QA Process</title> 208<title>Legal Issues</title>
124 <body> 209<body>
125
126 <p>The English developer's job is <e>extremely</e> important, as all translations have their roots
127 in our English documentation. So, it is imperative that the process described below is followed quite
128 pedantically.
129 </p>
130 210
131 <p>If not done already, the following documents need to be read before continuing: 211<p>
132 </p> 212Every document published by the Gentoo Documentation Project must be
213licensed by the <uri
214link="http://creativecommons.org/licenses/by-sa/2.0/">Creative Commons
215Attribution-ShareAlike License</uri>.
216</p>
133 217
134 <ul> 218<p>
135 <li><uri link="http://www.gentoo.org/doc/en/xml-guide.xml">The Gentoo Linux XML Guide</uri></li> 219Every document must have the following tag inside its GuideXML
136 </ul> 220sourcecode between the <c>&lt;/abstract&gt;</c> and the <c>&lt;version&gt;</c>
221tags:
222</p>
137 223
138 <p>The Gentoo Linux Documentation process can be broken down into several parts: 224<pre caption = "Licensing notice for the Gentoo Documentation">
139 </p> 225&lt;/abstract&gt;
140 226<i>
141 <p><b>The first step to submitting a new document or changing an existing document</b> 227&lt;!-- The content of this document is licensed under the CC-BY-SA license --&gt;
142 is filing a bug on our <uri link="http://bugs.gentoo.org">Bug System</uri>. This serves 228&lt;!-- See http://creativecommons.org/licenses/by-sa/2.0 --&gt;
143 as a notification to other developers and users alike that there is a work in process. 229&lt;license/&gt;
144 If there is already a bug in the database that requests a change to the documentation, 230</i>
145 a new bug does not have to be filed. 231&lt;version&gt;...&lt;/version&gt;
146 </p> 232</pre>
147 233
148 <p><b>When the proposed new document or change is completed</b>, two courses of action can
149 be taken: </p>
150
151 <p>If the change/ bugfix is technical in nature, the revised document, along with its associated
152 bug number, must be posted to the <i>gentoo-docs-review@gentoo.org</i> mailinglist for technical
153 review. This step is incredibly important, as it ensures the technical accuracy of our documentation.
154 The document in question <e>cannot</e> be committed to CVS unless it is submitted for review.</p>
155
156 <p>If the change/ bugfix is grammatical or syntactical in nature, all that is needed is a short note
157 to <i>gentoo-docs-review@gentoo.org</i> stating the bug number if applicable, and the fix. </p>
158
159 <p><b>Once the document is in CVS</b>, a Senior Developer will be notified, and the Document will
160 be posted to the live document index page. </p>
161
162 </body> 234</body>
163 </section> 235</section>
236<section>
237<title>Bugs and Updates</title>
238<body>
239
240<p>
241Every bug reported on <uri link="http://bugs.gentoo.org">bugs.gentoo.org</uri>
242should be handled as fast as possible. If a bug cannot be handled
243in a timely fashion, the reporter of that bug should be informed about
244this using a comment on the bug. The tactical or operational manager can
245decide that a bug has a higher priority and should be handled first before any
246other task the assingee is responsible of.
247</p>
248
249<p>
250Whenever a Gentoo Documentation Team member takes care of a bug, he or
251she 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
253of the operational manager, a bug may not be taken away from another
254Gentoo 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>
264Every document the Gentoo Documentation Team develops can be developed
265as the related parties see fit. However, when the document is finished,
266it should be transformed into <uri
267link="http://www.gentoo.org/doc/en/xml-guide.xml">GuideXML</uri>.
268</p>
269
270<p>
271When a new document is started or a big change is needed, a bug should be filed
272at <uri link="http://bugs.gentoo.org">bugs.gentoo.org</uri>
273concerning the development of this document. If there is already a bug
274in the database that requests a change to the documentation, a new bug
275does not have to be filed. Grammatical, syntactical or small changes
276do not require a bug to be filed on <uri
277link="http://bugs.gentoo.org">bugs.gentoo.org</uri> as well.
278</p>
279
280<p>
281All changes in contents of the document, except for typo fixes in text
282itself or in the comments to code listings, should lead to version
283number (and date) increase. Note that the change of a Code Listings should
284definitely cause an increase of the version number and date.
285</p>
286
287<p>
288When 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
291once (which also means an identical commit message).
292</p>
293
294<p>
295All changes in XML formatting should lead to version (and date) bumps only in
296case the layout of the document changes.
297</p>
298
299<p>
300Whether or not to increment the major version number instead of minor version
301number or other is up to the editor.
302</p>
303
304<p>
305Every update of a translation should copy the new version information
306verbatim from the master English document so fully synchronised
307translations 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>
317To keep a high-pace development cycle of the documentation, technical or
318intrusive 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
320you are not 100% confident (for instance because a user has told you how to fix
321it but you cannot verify yourself), have the change reviewed by a Gentoo
322Developer that can verify the change.
323</p>
324
325<p>
326High volume, technical or intrusive changes must be accompanied by a bugreport
327on <uri>http://bugs.gentoo.org</uri>. This bugnumber <e>must</e> be mentioned in
328the CVS log to allow backtracing of changes.
329</p>
330
331<p>
332If a bugfix consists out of both content as internal coding changes,
333both changes must be committed seperately so that translators can easily
334view the important changes (content) and ignore the coding changes.
335</p>
336
337<p>
338In case of a translation, the lead translator of the language is
339responsible for the document. Only he or she may commit the document to CVS
340unless he or she is currently "in training", in which case his or her
341mentor should commit it.
342</p>
343
344</body>
345</section>
346<section>
347<title>Sanctions</title>
348<body>
349
350<p>
351Although this has never been necessary, it is still important to list this in
352the policy - even though it is hateful. Anyway, documentation developers that
353misuse 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>
371will be reported to the <uri link="/proj/en/devrel">Gentoo Developer
372Relations</uri> project.
373</p>
374
375</body>
376</section>
164</chapter> 377</chapter>
165 378
166
167<chapter> 379<chapter>
168 <title>Translator Guidelines</title> 380<title>Documentation Team Recruitement</title>
169 <section> 381<section>
170 <title>QA Process</title> 382<title>Contributors, Authors, Translators</title>
171 <body> 383<body>
172
173 <p>Translators will follow the English Developer's QA process, but with the following exceptions:
174 </p>
175 384
176 <p><b>Each language will have a translation team, with an Offical Gentoo Linux Translator</b> as their head. 385<p>
177 All translations will be filtered through this lead person. The lead translator will make certain that the 386Everyone interested in contributing documentation, editing existing
178 translated documents are grammatically and syntactically perfect. The lead translator will have limited CVS 387documentation, writing new documentation or translating documentation is
179 access which will enable them to commit documents in a timely manner. </p> 388welcome to join the team. There are no rules or strings attached to
180 389this. Just make sure you are subscribed to <c>gentoo-doc@gentoo.org</c>
181 <p>If not done already, the following documents need to be read before continuing: 390and you have fully read this policy and understand it.
182 </p> 391</p>
183 392
184 <ul>
185 <li><uri link="http://www.gentoo.org/doc/en/xml-guide.xml">The Gentoo Linux XML Guide</uri></li>
186 </ul>
187 <p>The translator's QA process is as follows:</p>
188
189 <p><b>The first step to submitting a new document or changing an existing document</b>
190 is filing a bug on our <uri link="http://bugs.gentoo.org">Bug System</uri>. This serves
191 as a notification to other developers and users alike that there is a work in process.
192 If there is already a bug in the database that requests a change to the documentation,
193 a new bug does not have to be filed. </p>
194
195 <p><b>When the proposed new document or change is completed</b>, a notification is to be sent to the
196 translation lead, and the translation lead is to make positively sure that the translated document is
197 perfect in every way.</p>
198
199 <p><b>Once the document and or change is carefully edited by the lead translator</b>, it can be moved
200 into CVS. </p>
201
202 <p><b>Once the document is in CVS</b>, a Senior Developer will be notified, and the Document will
203 be posted to the live document index page. </p>
204 </body> 393</body>
205 </section> 394</section>
395<section>
396<title>Gentoo Documentation Developer</title>
397<body>
398
399<p>
400As a Gentoo documentation developer should know everything in the <uri
401link="http://www.gentoo.org/doc/en/policy.xml">Gentoo Policy</uri>
402even though you're not submitting ebuilds. You should also have read the
403<uri link="http://www.gentoo.org/doc/en/gentoo-release-policy.xml">Gentoo
404Release Policy</uri> and <uri
405link="http://www.gentoo.org/doc/en/management-structure.xml">Gentoo Management
406Structure</uri>. This is all needed to ensure our userbase that no Gentoo
407developer gives wrong information about critical things.
408</p>
409
410<p>
411Contact the operational manager of the Gentoo Documentation Project. He
412will ask you for your coordinates and other information and then arrange
413a mentor for you who will guide you through the first days or weeks as
414developer.
415</p>
416
417<p>
418You will be given a Gentoo e-mail address and be appointed to one or
419more subprojects. During the initial days or weeks, you should ask your
420mentor as much as possible, preferably have him/her double-check everything
421you do. If your function requires CVS access, you will only receive it
422when your mentor deems it appropriate. Until then, your mentor is in
423charge 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>
433Becoming a (follow-up) lead translator shouldn't be held lightly. You are
434responsible for every translated document and final reviewing. The lead
435translator will make certain that the translated documents are
436grammatically and syntactically perfect.
437</p>
438
439<p>
440In order to become a Gentoo (follow-up) lead translator you must be a Gentoo
441developer.
442</p>
443
444<p>
445During your "training" period you are a (follow-up) lead translator and
446should act upon it. All guidelines regarding (follow-up) lead translators
447apply.
448</p>
449
450</body>
451</section>
206</chapter> 452</chapter>
207
208<chapter>
209 <title>Documentation Contact List</title>
210 <section>
211 <title>Contact List</title>
212
213 <body>
214
215 <p>If you have any questions, please consult the appropriate person:
216 </p>
217
218 <table>
219 <tr><th>IRC Nick</th><th>Real Name</th><th>Duties</th></tr>
220 <tr><ti>ZhEN</ti><ti><mail link="zhen@gentoo.org">John P. Davis</mail></ti><ti>Documentation Coordinator</ti></tr>
221 <tr><ti>stocke2</ti><ti><mail link="stocke2@gentoo.org">Eric Stockbridge</mail></ti><ti>Website</ti></tr>
222 <tr><ti>rajiv</ti><ti><mail link="rajiv@gentoo.org">Rajiv</mail></ti><ti>PPC Documentation/ Website</ti></tr>
223 <tr><ti>nakano</ti><ti><mail link="nakano@gentoo.org">Masatomo Nakano</mail></ti><ti>Japanese Documentation</ti></tr>
224 <tr><ti>seo</ti><ti><mail link="seo@gentoo.org">Jungmin Seo</mail></ti><ti>Bug fixing/Korean Docs</ti></tr>
225 <tr><ti>BaSS</ti><ti><mail link="bass@gentoo.org">BaSS</mail></ti><ti>Spanish Documentation</ti></tr>
226 <tr><ti>SwifT</ti><ti><mail link="swift@gentoo.org">Sven Vermeulen</mail></ti><ti>Bug Fixing/Dutch Documentation</ti></tr>
227 <tr><ti>george</ti><ti><mail link="george@gentoo.org">George Shapovalov</mail></ti><ti>Russian Documentation</ti></tr>
228 <tr><ti>Pylon</ti><ti><mail link="pylon@gentoo.org">Lars Weiler</mail></ti><ti>German Documentation</ti></tr>
229 <tr><ti>Arachne</ti><ti><mail link="arachne@gentoo.org">Guillaume Morin</mail></ti><ti>French Documentation</ti></tr>
230 </table>
231
232 </body>
233 </section>
234</chapter>
235
236</guide> 453</guide>

Legend:
Removed from v.1.2  
changed lines
  Added in v.1.3

  ViewVC Help
Powered by ViewVC 1.1.20