/[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.1 - (show annotations) (download) (as text)
Fri Jul 4 18:20:27 2003 UTC (10 years, 9 months ago) by zhen
Branch: MAIN
File MIME type: application/xml
new GDP pages

1 <?xml version='1.0' encoding="UTF-8"?>
2 <?xml-stylesheet href="/xsl/guide.xsl" type="text/xsl"?>
3 <!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
4
5 <guide link="/proj/en/gdp/doc/doc-developer-guide.xml">
6
7 <title>Gentoo Linux Documentation Policy</title>
8 <author title="Author"><mail link="zhen@gentoo.org">John P. Davis</mail></author>
9 <abstract>
10 This guide explains the current Gentoo Documentation Policy.
11 </abstract>
12
13 <version>2.1.1</version>
14 <date>1 April 2003</date>
15
16 <chapter>
17 <title>Introduction</title>
18 <section>
19 <title>Introduction</title>
20 <body>
21
22 <p><B>The Gentoo Linux Documentation team aspires to create exceptionally professional
23 documentation that is immediately clear and concise to the end user</B>. In order to
24 fulfill this goal, we have very specific rules and guidelines that <e>all</e>
25 documentation must go through before it is published on our website, or otherwise.
26 </p>
27
28 </body>
29 </section>
30
31 <section>
32 <title>Covered Topics</title>
33 <body>
34
35 <p>This policy will cover these topics: </p>
36 <ul>
37 <li>Documentation Team Organization</li>
38 <li>English Developer Guidelines </li>
39 <li>Translator Guidelines</li>
40 <li>Contact Lists </li>
41 </ul>
42
43 </body>
44 </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>
83
84 <chapter>
85 <title>Documentation Team Organization</title>
86 <section>
87 <title>Organization</title>
88 <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
94 <p><b>Technical Writers: </b>The technical writers' function is to completely
95 document every aspect of Gentoo Linux. The writers will periodically be given
96 assignments by the Senior Developers, and those assignments are to take precedence
97 over any other Gentoo Linux development work. Although the writers' work is
98 ultimately proofed by the <b>Editing Team</b>, the writers <e>will still</e>
99 proof their own work before submitting it to the <i>gentoo-docs-review@gentoo.org</i>
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
103 <p><b>Editors/ Proofreaders: </b>The editors are in charge of editing and proofing
104 all changes to the Gentoo Linux Documentation. No change can be made unless it is
105 verified to be grammatically and syntactically correct by an Editor. The Editors
106 must make absolutely sure that <e>all</e> documentation going live on the website
107 is as professional and grammatically correct as possible. All Editors must
108 be subscribed to the <i>gentoo-docs-review@gentoo.org</i> mailing list.</p>
109
110 <p><b>Translators: </b>Due to the special nature of translations, the translators
111 are broken into their own team. Each language will have a lead Developer which will
112 serve as the Editor and CVS publisher. Once the lead translator has deemed that
113 a translation is ready to go live on the documentation index page, they may add it.
114 After the translation is added, a notice must be sent to the <i>gentoo-docs-review@gentoo.org</i>
115 mailing list.</p>
116 </body>
117 </section>
118 </chapter>
119
120 <chapter>
121 <title>English Developer Guidelines</title>
122 <section>
123 <title>QA Process</title>
124 <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
131 <p>If not done already, the following documents need to be read before continuing:
132 </p>
133
134 <ul>
135 <li><uri link="http://www.gentoo.org/doc/en/xml-guide.xml">The Gentoo Linux XML Guide</uri></li>
136 </ul>
137
138 <p>The Gentoo Linux Documentation process can be broken down into several parts:
139 </p>
140
141 <p><b>The first step to submitting a new document or changing an existing document</b>
142 is filing a bug on our <uri link="http://bugs.gentoo.org">Bug System</uri>. This serves
143 as a notification to other developers and users alike that there is a work in process.
144 If there is already a bug in the database that requests a change to the documentation,
145 a new bug does not have to be filed.
146 </p>
147
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>
163 </section>
164 </chapter>
165
166
167 <chapter>
168 <title>Translator Guidelines</title>
169 <section>
170 <title>QA Process</title>
171 <body>
172
173 <p>Translators will follow the English Developer's QA process, but with the following exceptions:
174 </p>
175
176 <p><b>Each language will have a translation team, with an Offical Gentoo Linux Translator</b> as their head.
177 All translations will be filtered through this lead person. The lead translator will make certain that the
178 translated documents are grammatically and syntactically perfect. The lead translator will have limited CVS
179 access which will enable them to commit documents in a timely manner. </p>
180
181 <p>If not done already, the following documents need to be read before continuing:
182 </p>
183
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>
205 </section>
206 </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>

  ViewVC Help
Powered by ViewVC 1.1.20