/[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.14 Revision 1.15
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.14 2005/06/02 16:48:26 swift Exp $ --> 2<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/proj/en/gdp/doc/doc-policy.xml,v 1.15 2005/06/02 16:58:03 swift Exp $ -->
3 3
4<!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> 4<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
5 5
6<guide link="doc-policy.xml"> 6<guide link="doc-policy.xml">
7 7
25Contributers should know and exercise. 25Contributers should know and exercise.
26</abstract> 26</abstract>
27 27
28<license/> 28<license/>
29 29
30<version>3.12</version> 30<version>3.13</version>
31<date>2005-06-02</date> 31<date>2005-06-02</date>
32 32
33<chapter> 33<chapter>
34<title>Introduction</title> 34<title>Introduction</title>
35<section> 35<section>
38 38
39<p> 39<p>
40The Gentoo Linux Documentation team aspires to create exceptionally 40The Gentoo Linux Documentation team aspires to create exceptionally
41professional documentation that is immediately clear and concise to the 41professional documentation that is immediately clear and concise to the
42end user. In order to fulfill this goal, we have very specific rules and 42end user. In order to fulfill this goal, we have very specific rules and
43guidelines that <e>all</e> documentation must go through prior to 43guidelines that <e>all</e> documentation must go through prior to
44dissemination on our website, or otherwise. 44dissemination on our website, or otherwise.
45</p> 45</p>
46 46
47</body> 47</body>
48</section> 48</section>
70<title>Organization</title> 70<title>Organization</title>
71<body> 71<body>
72 72
73<p> 73<p>
74The Gentoo Documentation Project Team is split into several smaller teams 74The Gentoo Documentation Project Team is split into several smaller teams
75that operate in complete cooperation with each other. Each smaller team 75that work in tandem with each other. Each smaller team represents an active
76represents an active development team of a Gentoo Documentation 76development team of a Gentoo Documentation Subproject.
77Subproject.
78</p> 77</p>
79 78
80<p> 79<p>
81The Gentoo Documentation Project is strategically led by a top-level Manager 80The Gentoo Documentation Project is strategically led by a top-level Manager
82as required by the <uri link="/doc/en/management-structure.xml">Gentoo 81as required by the <uri link="/doc/en/management-structure.xml">Gentoo
84of the Strategic Manager with respect to Gentoo Linux. 83of the Strategic Manager with respect to Gentoo Linux.
85</p> 84</p>
86 85
87<p> 86<p>
88For day-to-day managerial tasks, the Gentoo Documentation Project has an 87For day-to-day managerial tasks, the Gentoo Documentation Project has an
89Operational Manager. This person keeps track of all documentation-related tasks 88Operational Manager. This person keeps track of all short-term tasks
90that are more short-term. The Operational Manager and Strategic Manager can be 89related to documentation. The Operational Manager and Strategic Manager can be
91one and the same if the Strategic Manager wishes so. 90one and the same if the Strategic Manager wishes so.
92</p> 91</p>
93 92
94<p> 93<p>
95Currently these positions are taken by the following people: 94Currently these positions are taken by the following people:
114</table> 113</table>
115 114
116<p> 115<p>
117Every subproject has a Strategic Manager of its own and may have an 116Every subproject has a Strategic Manager of its own and may have an
118Operational Manager if deemed appropriate. His responsibilities to the Gentoo 117Operational Manager if deemed appropriate. His responsibilities to the Gentoo
119Documentation Project are the same as are listed on the <uri 118Documentation Project (GDP) are listed in the <e>Manager responsibilities</e>
119section of the <uri
120link="/doc/en/management-structure.xml#doc_chap1_sect5">Gentoo Management 120link="/doc/en/management-structure.xml#doc_chap1_sect5">Gentoo Management
121Structure</uri>. 121Structure</uri> document.
122</p>
123
124<p> 122</p>
125The subprojects of the Gentoo Documentation Team together with their respective 123
126Strategic Managers are listed on the <uri link="/proj/en/gdp/">GDP
127Website</uri>.
128</p> 124<p>
129 125Every subproject of the Gentoo Documentation Team is listed on the
126<uri link="/proj/en/gdp/">GDP Webpage</uri>, along with their respective
127Strategic Managers.
130<p> 128</p>
129
130<p>
131The decision on adding subprojects is in hands of the strategic Manager. 131The decision on adding a subproject is in the hands of the Strategic Manager.
132</p> 132</p>
133 133
134</body> 134</body>
135</section> 135</section>
136<section> 136<section>
153team about bugs regarding the Gentoo Documentation. You can add yourself by 153team about bugs regarding the Gentoo Documentation. You can add yourself by
154editing <path>/var/mail/alias/misc/docs-team</path> on dev.gentoo.org. 154editing <path>/var/mail/alias/misc/docs-team</path> on dev.gentoo.org.
155</p> 155</p>
156 156
157<p> 157<p>
158Every member of the Gentoo Documentation Team should be available at 158Members of the Gentoo Documentation Team should be available at
159<c>#gentoo-doc</c> on <uri link="http://www.freenode.net">irc.freenode.net</uri> 159<c>#gentoo-doc</c> on <uri link="http://www.freenode.net">irc.freenode.net</uri>
160whenever he is online. 160whenever they are online.
161</p>
162
163<p> 161</p>
162
163<p>
164Depending on his responsibilities, he can have limited CVS 164Depending on the assignment or responsibilities, a member may have limited CVS
165access to <c>cvs.gentoo.org</c>. Full CVS access can only be given to Gentoo 165access to <c>cvs.gentoo.org</c>. Full CVS access is restricted to Gentoo
166developers. Read-only CVS access can be given to recruits. 166Developers. Read-only CVS access may be granted to recruits.
167</p> 167</p>
168 168
169</body> 169</body>
170</section> 170</section>
171<section> 171<section>
172<title>Documentation Translation Teams</title> 172<title>Documentation Translation Teams</title>
173<body> 173<body>
174 174
175<p> 175<p>
176Every language should be backed up by an official translation team. This 176Every language should be backed up by an official Translation Team. This
177team is lead by a Lead Translator and perhaps a Follow-up Lead Translator, who 177team is led by a <e>Lead Translator</e> and perhaps a <e>Follow-On Lead
178both have CVS commit access. If for any reason the Lead Translator cannot 178Translator</e>, who both have CVS commit access. If for any reason the
179perform his or her duties, the Follow-up Lead Translator is in charge. If 179<e>Lead Translator</e> cannot perform his duties, the <e>Follow-On Lead
180even this person is unavailable, the mentor(s) is/are in charge of the language. 180Translator</e> is in charge. If the <e>Follow-On</e> is unavailable, the
181</p> 181mentor(s) is/are in charge of the language.
182
183<p> 182</p>
184If a translated document is contributed, but the language in itself is 183
185not supported, the Gentoo Documentation Team will not publish it
186officially. In this case the document will stay unlinked until an official
187translation team of that language is formed.
188</p> 184<p>
189 185If a translated document for an unsupported language is contributed, the Gentoo
186Documentation Team will not publish it officially. Such documents shall not be
187linked to the website until an official Translation Team of that language is
188formed.
190<p> 189</p>
190
191<p>
191When a language is officially supported, but the team doesn't have any 192When a language is officially supported, but the team does not have any
192members or no one wants to take on the responsibilities of the Lead 193members willing to take on the responsibilities of the <e>Lead
193Translator, all links to the documents will be removed from the site. 194Translator</e>, all links to the documents will be removed from the site.
194However, the documents will stay available in case the language becomes 195However, the documents will stay available in case the language becomes
195officially supported again. 196officially supported again.
197</p>
198
199<p>
200For more information Gentoo document translations, please consult the
201<uri link="/proj/en/gdp/doc/translators-howto.xml">
202Translators Howto for Gentoo Documentation</uri> and the
203<uri link="/proj/en/gdp/international.xml">
204GDP Internationalisation Subproject</uri> page.
196</p> 205</p>
197 206
198</body> 207</body>
199</section> 208</section>
200</chapter> 209</chapter>
238Every bug reported on <uri link="http://bugs.gentoo.org">bugs.gentoo.org</uri> 247Every bug reported on <uri link="http://bugs.gentoo.org">bugs.gentoo.org</uri>
239should be handled as fast as possible. If a bug cannot be handled 248should be handled as fast as possible. If a bug cannot be handled
240in a timely fashion, the reporter of that bug should be informed about 249in a timely fashion, the reporter of that bug should be informed about
241this using a comment on the bug and the bug should be registered in the 250this using a comment on the bug and the bug should be registered in the
242<uri link="/proj/en/gdp/doc/metadoc-guide.xml">metadoc.xml</uri> file, if 251<uri link="/proj/en/gdp/doc/metadoc-guide.xml">metadoc.xml</uri> file, if
243applicable. The Tactical or Operational Manager may decide that a bug has a 252applicable. The Strategic or Operational Manager may decide that a bug has a
244higher priority and should be addressed ahead any other task the assingee 253higher priority and should be addressed ahead any other task the assignee
245is responsible of. 254is responsible for.
246</p> 255</p>
247 256
248<p> 257<p>
249Whenever a Gentoo Documentation Team member takes care of a bug, he or 258Whenever a Gentoo Documentation Team member takes care of a bug, he or
250she should assign the bug to herself/himself, but make sure that 259she should assign the bug to herself/himself, but make sure that
251<c>docs-team@gentoo.org</c> is on the Cc-list. Unless with the consent 260<c>docs-team@gentoo.org</c> is on the Cc-list. A bug may not be taken away from
252of the Operational Manager, a bug may not be taken away from another
253Gentoo Documentation Team member without their approval. 261another Gentoo Documentation Team member without their approval; unless consent
262has been received from the Operational Manager.
254</p> 263</p>
255 264
256</body> 265</body>
257</section> 266</section>
258<section> 267<section>
259<title>Document Development</title> 268<title>Document Development</title>
260<body> 269<body>
261 270
262<p> 271<p>
263Every document the Gentoo Documentation Team develops can be developed as the 272Every Gentoo Documentation Team may handle documentation development as it sees
264related parties see fit. However, when the document is finished, it should be 273fit. However, when the document is finished, it should be transformed into
265transformed into <uri link="/doc/en/xml-guide.xml">GuideXML</uri> and put 274<uri link="/doc/en/xml-guide.xml">GuideXML</uri> and made available on the
266available on the Gentoo CVS infrastructure. It must also be registered in the 275Gentoo CVS infrastructure. It must also be registered in the
267<uri link="/proj/en/gdp/doc/metadoc-guide.xml">metadoc.xml</uri> file if 276<uri link="/proj/en/gdp/doc/metadoc-guide.xml">metadoc.xml</uri> file if
268applicable. 277applicable.
269</p> 278</p>
270 279
271<p> 280<p>
306<section> 315<section>
307<title>Reviewing and Committing</title> 316<title>Reviewing and Committing</title>
308<body> 317<body>
309 318
310<p> 319<p>
311To keep a high-pace development cycle of the documentation, technical or 320To maintain a high-paced documentation development cycle, technical or
312intrusive changes to documents can be propagated immediately to the document 321intrusive changes to documents can be propagated immediately to the document.
313<e>if</e> the editor is 100% confident his changes are correct and working. If 322This is allowed only <e>if</e> the editor is absolutely confident the changes
314you are not 100% confident (for instance because a user has told you how to fix 323are functional. If you are not absolutely confident (for instance because a
315it but you cannot verify yourself), have the change reviewed by a Gentoo 324user has told you how to fix it but you cannot verify yourself), have the
316Developer that can verify the change. 325changes reviewed by a Gentoo Developer that can verify the changes are apt.
317</p>
318
319<p> 326</p>
327
328<p>
320High volume, technical or intrusive changes must be accompanied by a bugreport 329High-volume, technical or intrusive changes must be accompanied by a bug report
321on <uri>http://bugs.gentoo.org</uri>. This bug number <e>must</e> be mentioned 330on <uri>http://bugs.gentoo.org</uri>. This bug number <e>must</e> be mentioned
322in the CVS log to allow backtracing of changes. 331in the CVS log to allow backtracing of changes.
323</p> 332</p>
324 333
325<p> 334<p>
326If a bugfix consists out of both content as internal coding changes, 335If a bugfix includes changes to content as well as internal coding changes,
327both changes must be committed separately so that translators can easily 336both changes must be committed separately. This allows translators to focus
328view the important changes (content) and ignore the coding changes. 337on the relevant changes regarding content and ignore the coding changes.
329</p>
330
331<p> 338</p>
332In case of a translation, the Lead Translator of the language is 339
333responsible for the document. Only he may commit the document to CVS 340<p>
334unless he is currently "in training", in which case his or her 341If the document in question is a translation, the <e>Lead Translator</e> of the
335mentor should commit it. 342affected language is responsible for the document. Only the
343<e>Lead Translator</e> may commit the document to the CVS repository. However,
344if the <e>Lead Translator</e> is currently "in training", the trainee's mentor
345should commit the changes.
336</p> 346</p>
337 347
338</body> 348</body>
339</section> 349</section>
340<section> 350<section>
341<title>Sanctions</title> 351<title>Sanctions</title>
342<body> 352<body>
343 353
344<p> 354<p>
345Although this has never been necessary, it is still important to list this in 355Malicious conduct by developers has never been an issue. However, it should be
346the policy - even though it is hateful. Anyway, documentation developers that 356noted that documentation developers that misuse their position by
347misuse their position by
348</p> 357</p>
349 358
350<ul> 359<ul>
351 <li>deliberately providing wrong information to users or developers</li> 360 <li>deliberately providing wrong information to users or developers</li>
352 <li>deliberately writing flawed documentation</li> 361 <li>deliberately writing flawed documentation</li>
478<section> 487<section>
479<title>Phase 2: Read-Only CVS Access</title> 488<title>Phase 2: Read-Only CVS Access</title>
480<body> 489<body>
481 490
482<p> 491<p>
483During phase 2, the recruitee is given read-only access to the Gentoo 492During phase 2, the recruit is given read-only access to the Gentoo
484Documentation Repository, allowing him to generate commit-ready patches for the 493Documentation Repository, allowing him to generate commit-ready patches for
485tree. During this period, which is roughly the same as the aforementioned table, 494the tree. During this period, which is roughly the same as the aforementioned
486his patches are not edited by a documentation developer anymore, but are either 495table, his patches are not edited by a documentation developer anymore, but
487committed as-is or refused. The recruit is also assigned to a full-time 496are either committed as-is or refused. The recruit is also assigned to a
488documentation developer (the mentor) which will guide him through these last 497full-time documentation developer (the mentor) which will guide him through
489phases. 498these last phases.
490</p> 499</p>
491 500
492<p> 501<p>
493The quality of the contributions are in this phase most important - every patch 502The quality of the contributions are in this phase most important - every patch
494that does not follow the Documentation Policy, Coding Style or other guideline 503that does not follow the Documentation Policy, Coding Style or other guideline

Legend:
Removed from v.1.14  
changed lines
  Added in v.1.15

  ViewVC Help
Powered by ViewVC 1.1.20