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

1 zhen 1.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