/[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.20 Revision 1.21
1<?xml version='1.0' encoding="UTF-8"?> 1<?xml version='1.0' encoding="UTF-8"?>
2<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/proj/en/gdp/doc/doc-policy.xml,v 1.20 2005/12/22 22:24:11 neysx Exp $ --> 2<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/proj/en/gdp/doc/doc-policy.xml,v 1.21 2006/07/08 17:21:18 neysx Exp $ -->
3<!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> 3<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
4 4
5<guide link="doc-policy.xml"> 5<guide link="doc-policy.xml">
6 6
7<title>Gentoo Linux Documentation Policy</title> 7<title>Gentoo Linux Documentation Policy</title>
8<author title="Author"> 8<author title="Author">
9 <mail link="zhen@gentoo.org">John P. Davis</mail> 9 <mail link="zhen@gentoo.org">John P. Davis</mail>
10</author> 10</author>
11<author title="Author"> 11<author title="Author">
12 <mail link="swift@gentoo.org">Sven Vermeulen</mail> 12 <mail link="swift@gentoo.org">Sven Vermeulen</mail>
13</author> 13</author>
14<author title="Editor"> 14<author title="Editor">
15 <mail link="spyderous@gentoo.org">Donnie Berkholz</mail> 15 <mail link="dberkholz@gentoo.org">Donnie Berkholz</mail>
16</author> 16</author>
17 17
18<!-- The content of this document is licensed under the CC-BY-SA license --> 18<!-- The content of this document is licensed under the CC-BY-SA license -->
19<!-- See http://creativecommons.org/licenses/by-sa/2.5 --> 19<!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
20 20
34<section> 34<section>
35<title>Introduction</title> 35<title>Introduction</title>
36<body> 36<body>
37 37
38<p> 38<p>
39The Gentoo Linux Documentation team aspires to create exceptionally 39The Gentoo Linux Documentation team aspires to create exceptionally
40professional documentation that is immediately clear and concise to the 40professional documentation that is immediately clear and concise to the
41end user. In order to fulfill this goal, we have very specific rules and 41end user. In order to fulfill this goal, we have very specific rules and
42guidelines that <e>all</e> documentation must go through prior to 42guidelines that <e>all</e> documentation must go through prior to
43dissemination on our website, or elsewhere. 43dissemination on our website, or elsewhere.
44</p> 44</p>
45 45
46</body> 46</body>
48<section> 48<section>
49<title>Covered Topics</title> 49<title>Covered Topics</title>
50<body> 50<body>
51 51
52<p> 52<p>
53This policy will cover the following topics: 53This policy will cover the following topics:
54</p> 54</p>
55 55
56<ul> 56<ul>
57<li>Documentation Project Team Organization</li> 57<li>Documentation Project Team Organization</li>
58<li>Documentation Guidelines</li> 58<li>Documentation Guidelines</li>
69<title>Organization</title> 69<title>Organization</title>
70<body> 70<body>
71 71
72<p> 72<p>
73The Gentoo Documentation Project Team is split into several smaller teams 73The Gentoo Documentation Project Team is split into several smaller teams
74that work in tandem with each other. Each smaller team represents an active 74that work in tandem with each other. Each smaller team represents an active
75development team of a Gentoo Documentation Subproject. 75development team of a Gentoo Documentation Subproject.
76</p> 76</p>
77 77
78<!-- 78<!--
79<p> 79<p>
112 <ti><mail link="neysx@gentoo.org">neysx</mail></ti> 112 <ti><mail link="neysx@gentoo.org">neysx</mail></ti>
113</tr> 113</tr>
114</table> 114</table>
115 115
116<p> 116<p>
117Every subproject has a Strategic Manager of its own, and may have an 117Every subproject has a Strategic Manager of its own, and may have an
118Operational Manager if deemed appropriate. His responsibilities to the Gentoo 118Operational Manager if deemed appropriate. His responsibilities to the Gentoo
119Documentation Project (GDP) are listed in the <e>Manager responsibilities</e> 119Documentation Project (GDP) are listed in the <e>Manager responsibilities</e>
120section of the <uri 120section of the <uri
121link="/doc/en/management-structure.xml#doc_chap1_sect5">Gentoo Management 121link="/doc/en/management-structure.xml#doc_chap1_sect5">Gentoo Management
122Structure</uri> document. 122Structure</uri> document.
123</p> 123</p>
124 124
125<p> 125<p>
126Every subproject of the Gentoo Documentation Team is listed on the 126Every subproject of the Gentoo Documentation Team is listed on the
127<uri link="/proj/en/gdp/">GDP Webpage</uri>, along with their respective 127<uri link="/proj/en/gdp/">GDP Webpage</uri>, along with their respective
128Strategic Managers. 128Strategic Managers.
129</p> 129</p>
130 130
131<p> 131<p>
132The decision on adding a subproject is in the hands of the Strategic Manager. 132The decision on adding a subproject is in the hands of the Strategic Manager.
133</p> 133</p>
134 134
135</body> 135</body>
136</section> 136</section>
137<section> 137<section>
156</p> 156</p>
157 157
158<p> 158<p>
159Members of the Gentoo Documentation Team should be available at 159Members of the Gentoo Documentation Team should be available at
160<c>#gentoo-doc</c> on <uri link="http://www.freenode.net">irc.freenode.net</uri> 160<c>#gentoo-doc</c> on <uri link="http://www.freenode.net">irc.freenode.net</uri>
161whenever they are online. 161whenever they are online.
162</p>
163
164<p> 162</p>
163
164<p>
165Depending on the assignment or responsibilities, a member may have limited CVS 165Depending on the assignment or responsibilities, a member may have limited CVS
166access to <c>cvs.gentoo.org</c>. Full CVS access is restricted to Gentoo 166access to <c>cvs.gentoo.org</c>. Full CVS access is restricted to Gentoo
167Developers. Read-only CVS access may be granted to recruits. 167Developers. Read-only CVS access may be granted to recruits.
168</p> 168</p>
169 169
170</body> 170</body>
173<title>Documentation Translation Teams</title> 173<title>Documentation Translation Teams</title>
174<body> 174<body>
175 175
176<p> 176<p>
177Every language should be backed up by an official Translation Team. This 177Every language should be backed up by an official Translation Team. This
178team is led by a <e>Lead Translator</e> and perhaps a <e>Follow-On Lead 178team is led by a <e>Lead Translator</e> and perhaps a <e>Follow-On Lead
179Translator</e>, who both have CVS commit access. If for any reason the 179Translator</e>, who both have CVS commit access. If for any reason the
180<e>Lead Translator</e> cannot perform his duties, the <e>Follow-On Lead 180<e>Lead Translator</e> cannot perform his duties, the <e>Follow-On Lead
181Translator</e> is in charge. If the <e>Follow-On</e> is unavailable, the 181Translator</e> is in charge. If the <e>Follow-On</e> is unavailable, the
182mentor(s) is/are in charge of the language. 182mentor(s) is/are in charge of the language.
183</p> 183</p>
184 184
185<p> 185<p>
186If a translated document for an unsupported language is contributed, the Gentoo 186If a translated document for an unsupported language is contributed, the Gentoo
187Documentation Team will not publish it officially. Such documents shall not be 187Documentation Team will not publish it officially. Such documents shall not be
188linked to the website until an official Translation Team of that language is 188linked to the website until an official Translation Team of that language is
189formed. 189formed.
190</p> 190</p>
191 191
192<p> 192<p>
193When a language is officially supported, but the team does not have any 193When a language is officially supported, but the team does not have any
196However, the documents will stay available in case the language becomes 196However, the documents will stay available in case the language becomes
197officially supported again. 197officially supported again.
198</p> 198</p>
199 199
200<p> 200<p>
201For more information Gentoo document translations, please consult the 201For more information Gentoo document translations, please consult the
202<uri link="/proj/en/gdp/doc/translators-howto.xml"> 202<uri link="/proj/en/gdp/doc/translators-howto.xml">
203Translators Howto for Gentoo Documentation</uri> and the 203Translators Howto for Gentoo Documentation</uri> and the
204<uri link="/proj/en/gdp/international.xml"> 204<uri link="/proj/en/gdp/international.xml">
205GDP Internationalisation Subproject</uri> page. 205GDP Internationalisation Subproject</uri> page.
206</p> 206</p>
207 207
208</body> 208</body>
215<title>Legal Issues</title> 215<title>Legal Issues</title>
216<body> 216<body>
217 217
218<p> 218<p>
219Every document published by the Gentoo Documentation Project must be 219Every document published by the Gentoo Documentation Project must be
220licensed by the <uri 220licensed by the <uri
221link="http://creativecommons.org/licenses/by-sa/2.5/">Creative Commons 221link="http://creativecommons.org/licenses/by-sa/2.5/">Creative Commons
222Attribution-ShareAlike License</uri>. 222Attribution-ShareAlike License</uri>.
223</p> 223</p>
224 224
225<p> 225<p>
226Every document must have the following tag inside its GuideXML 226Every document must have the following tag inside its GuideXML
227source code between the <c>&lt;/abstract&gt;</c> and the <c>&lt;version&gt;</c> 227source code between the <c>&lt;/abstract&gt;</c> and the <c>&lt;version&gt;</c>
244<title>Bugs and Updates</title> 244<title>Bugs and Updates</title>
245<body> 245<body>
246 246
247<p> 247<p>
248Every bug reported on <uri link="http://bugs.gentoo.org">bugs.gentoo.org</uri> 248Every bug reported on <uri link="http://bugs.gentoo.org">bugs.gentoo.org</uri>
249should be handled as fast as possible. If a bug cannot be handled 249should be handled as fast as possible. If a bug cannot be handled
250in a timely fashion, the reporter of that bug should be informed about 250in a timely fashion, the reporter of that bug should be informed about
251this using a comment on the bug, and the bug should be registered in the 251this using a comment on the bug, and the bug should be registered in the
252<uri link="/proj/en/gdp/doc/metadoc-guide.xml">metadoc.xml</uri> file, if 252<uri link="/proj/en/gdp/doc/metadoc-guide.xml">metadoc.xml</uri> file, if
253applicable. The Strategic or Operational Manager may decide that a bug has a 253applicable. The Strategic or Operational Manager may decide that a bug has a
254higher priority and should be addressed ahead any other task the assignee 254higher priority and should be addressed ahead any other task the assignee
255is responsible for. 255is responsible for.
256</p> 256</p>
257 257
269<title>Document Development</title> 269<title>Document Development</title>
270<body> 270<body>
271 271
272<p> 272<p>
273Every Gentoo Documentation Team may handle documentation development as it sees 273Every Gentoo Documentation Team may handle documentation development as it sees
274fit. However, when the document is finished, it should be transformed into 274fit. However, when the document is finished, it should be transformed into
275<uri link="/doc/en/xml-guide.xml">GuideXML</uri> and made available on the 275<uri link="/doc/en/xml-guide.xml">GuideXML</uri> and made available on the
276Gentoo CVS infrastructure. It must also be registered in the 276Gentoo CVS infrastructure. It must also be registered in the
277<uri link="/proj/en/gdp/doc/metadoc-guide.xml">metadoc.xml</uri> file if 277<uri link="/proj/en/gdp/doc/metadoc-guide.xml">metadoc.xml</uri> file if
278applicable. 278applicable.
279</p> 279</p>
280 280
281<p> 281<p>
282When a new document is started or a big change is needed, a bug should be filed 282When a new document is started or a big change is needed, a bug should be filed
283at <uri link="http://bugs.gentoo.org">bugs.gentoo.org</uri> 283at <uri link="http://bugs.gentoo.org">bugs.gentoo.org</uri>
284concerning the development of this document. If there is already a bug 284concerning the development of this document. If there is already a bug
285in the database that requests a change to the documentation, a new bug 285in the database that requests a change to the documentation, a new bug
286does not have to be filed. Grammatical, syntactical or small changes 286does not have to be filed. Grammatical, syntactical or small changes
287do not require a bug to be filed on <uri 287do not require a bug to be filed on <uri
288link="http://bugs.gentoo.org">bugs.gentoo.org</uri> as well. 288link="http://bugs.gentoo.org">bugs.gentoo.org</uri> as well.
289</p> 289</p>
290 290
291<p> 291<p>
292All changes in contents of the document, except for typo fixes in text 292All changes in contents of the document, except for typo fixes in text
294number (and date) increase. Note that the change of a Code Listings should 294number (and date) increase. Note that the change of a Code Listings should
295definitely cause an increase of the version number and date. 295definitely cause an increase of the version number and date.
296</p> 296</p>
297 297
298<p> 298<p>
299All changes in XML formatting should lead to version (and date) bumps only in 299All changes in XML formatting should lead to version (and date) bumps only in
300case the layout of the document changes. 300case the layout of the document changes.
301</p> 301</p>
302 302
303<p> 303<p>
304Whether or not to increment the major version number instead of minor version 304Whether or not to increment the major version number instead of minor version
319 319
320<p> 320<p>
321To maintain a high-paced documentation development cycle, technical or 321To maintain a high-paced documentation development cycle, technical or
322intrusive changes to documents can be propagated immediately to the document. 322intrusive changes to documents can be propagated immediately to the document.
323This is allowed only <e>if</e> the editor is absolutely confident the changes 323This is allowed only <e>if</e> the editor is absolutely confident the changes
324are functional. If you are not absolutely confident (for instance because a 324are functional. If you are not absolutely confident (for instance because a
325user has told you how to fix it but you cannot verify yourself), have the 325user has told you how to fix it but you cannot verify yourself), have the
326changes reviewed by a Gentoo Developer that can verify the changes are apt. 326changes reviewed by a Gentoo Developer that can verify the changes are apt.
327</p> 327</p>
328 328
329<p> 329<p>
338on the relevant changes regarding content and ignore the coding changes. 338on the relevant changes regarding content and ignore the coding changes.
339</p> 339</p>
340 340
341<p> 341<p>
342If the document in question is a translation, the <e>Lead Translator</e> of the 342If the document in question is a translation, the <e>Lead Translator</e> of the
343affected language is responsible for the document. Only the 343affected language is responsible for the document. Only the
344<e>Lead Translator</e> may commit the document to the CVS repository. However, 344<e>Lead Translator</e> may commit the document to the CVS repository. However,
345if the <e>Lead Translator</e> is currently "in training", the trainee's mentor 345if the <e>Lead Translator</e> is currently "in training", the trainee's mentor
346should commit the changes. 346should commit the changes.
347</p> 347</p>
348 348
388 388
389<p> 389<p>
390Everyone interested in contributing documentation, editing existing 390Everyone interested in contributing documentation, editing existing
391documentation, writing new documentation or translating documentation is 391documentation, writing new documentation or translating documentation is
392welcome to join the team. There are no rules or strings attached to 392welcome to join the team. There are no rules or strings attached to
393this. Just make sure you are subscribed to <c>gentoo-doc@gentoo.org</c>, 393this. Just make sure you are subscribed to <c>gentoo-doc@gentoo.org</c>,
394and you have fully read this policy and understand it. 394and you have fully read this policy and understand it.
395</p> 395</p>
396 396
397</body> 397</body>
398</section> 398</section>
423<body> 423<body>
424 424
425<p> 425<p>
426No recruitment process starts without investigating the contributions done 426No recruitment process starts without investigating the contributions done
427already to the Gentoo Documentation Project. The number of contributions must be 427already to the Gentoo Documentation Project. The number of contributions must be
428large to assure a good knowledge of GuideXML, Coding Style and policy. The 428large to assure a good knowledge of GuideXML, Coding Style and policy. The
429contribution period must be large as well to inform the contributor about the 429contribution period must be large as well to inform the contributor about the
430time-consuming position and pressure the application involves. 430time-consuming position and pressure the application involves.
431</p> 431</p>
432 432
433<p> 433<p>
434The number of contributions and period over which the contributions should be 434The number of contributions and period over which the contributions should be
475Any request for CVS access that does not allow a development activity as written 475Any request for CVS access that does not allow a development activity as written
476down in the aforementioned table will not be taken into account. 476down in the aforementioned table will not be taken into account.
477</p> 477</p>
478 478
479<p> 479<p>
480If you feel that you have shown sufficient amount of contributions, contact 480If you feel that you have shown sufficient amount of contributions, contact
481the Operational Manager of the Gentoo Documentation Project. He 481the Operational Manager of the Gentoo Documentation Project. He
482will ask you for your coordinates and other information, and then arrange 482will ask you for your coordinates and other information, and then arrange
483for the next phase to be started. 483for the next phase to be started.
484</p> 484</p>
485 485
486</body> 486</body>
487</section> 487</section>
509During this period, you: 509During this period, you:
510</p> 510</p>
511 511
512<ul> 512<ul>
513 <li> 513 <li>
514 are advised to learn about Gentoo's inner workings. 514 are advised to learn about Gentoo's inner workings.
515 This is required as you will be asked later on to answer Gentoo's <uri 515 This is required as you will be asked later on to answer Gentoo's <uri
516 link="/proj/en/devrel/quiz/staff-quiz.txt">Staffing Quiz</uri>. 516 link="/proj/en/devrel/quiz/staff-quiz.txt">Staffing Quiz</uri>.
517 </li> 517 </li>
518 <li> 518 <li>
519 will be asked to fill in the <uri 519 will be asked to fill in the <uri
520 link="/proj/en/gdp/doc/doc-quiz.xml">Gentoo Documentation Project 520 link="/proj/en/gdp/doc/doc-quiz.xml">Gentoo Documentation Project
521 Quiz</uri>. You need to successfully pass this entire quiz (all questions) 521 Quiz</uri>. You need to successfully pass this entire quiz (all questions)
522 before you can continue with the next Phase. 522 before you can continue with the next Phase.
523 </li> 523 </li>
524</ul> 524</ul>
530<body> 530<body>
531 531
532<p> 532<p>
533When Phase 2 is finished, the Operational Manager will contact <uri 533When Phase 2 is finished, the Operational Manager will contact <uri
534link="/proj/en/devrel">Developer Relations</uri> and give a final "Go!" for the 534link="/proj/en/devrel">Developer Relations</uri> and give a final "Go!" for the
535Gentoo recruitment process after which you will be given a Gentoo e-mail 535Gentoo recruitment process after which you will be given a Gentoo e-mail
536address and be appointed to one or more subprojects. 536address and be appointed to one or more subprojects.
537</p> 537</p>
538 538
539</body> 539</body>
540</section> 540</section>
541</chapter> 541</chapter>

Legend:
Removed from v.1.20  
changed lines
  Added in v.1.21

  ViewVC Help
Powered by ViewVC 1.1.20