gdp/doc/doc-policy.xml

<?xml version='1.0' encoding="UTF-8"?>
<?xml-stylesheet href="/xsl/guide.xsl" type="text/xsl"?>
<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">

<guide link="/proj/en/gdp/doc/doc-developer-guide.xml">

<title>Gentoo Linux Documentation Policy</title>
<author title="Author"><mail link="zhen@gentoo.org">John P. Davis</mail></author>
<abstract>
        This guide explains the current Gentoo Documentation Policy.
</abstract>

<version>2.1.1</version>
<date>1 April 2003</date>

<chapter>
        <title>Introduction</title>
                <section>
                        <title>Introduction</title>
                        <body>
                        
                        <p><B>The Gentoo Linux Documentation team aspires to create exceptionally professional
                        documentation that is immediately clear and concise to the end user</B>. In order to 
                        fulfill this goal, we have very specific rules and guidelines that <e>all</e> 
                        documentation must go through before it is published on our website, or otherwise.
                        </p>
                
                </body>
                </section>

                <section>
                        <title>Covered Topics</title>
                        <body>

                        <p>This policy will cover these topics: </p>
                        <ul>
                        <li>Documentation Team Organization</li>
                        <li>English Developer Guidelines </li>
                        <li>Translator Guidelines</li>
                        <li>Contact Lists </li>
                        </ul>

                        </body>
                </section>
                
                <section>
                        <title>Preliminaries</title>
                        <body>
                        <p>Before continuing, it is expected that all documentation developers be subscribed to
                        the <i>gentoo-doc@gentoo.org</i> mailinglist, and that they are readily available in
                        <i>#gentoo-doc</i> at all times.
                        </p>

                        <p>Additionally, some functional definitions are needed in order to specifically outline
                        the duties and responsibilities of the documentation team. </p>

                        <p><b>Official Gentoo Linux Documentation</b> is simply defined as any documentation
                        that is released by Gentoo Linux for consumption by the end user. The only exceptions to
                        this are the Gentoo Weekly Newsletter, and the <i>gentoo.org</i> website, which
                        are maintained by their own respective teams. </p>

                        <p>Gentoo Linux Documentation can be separated into two categories, critical and
                        non-critical documentation. </p>

                        <p><b>Critical Documentation</b> is defined as any documentation that is <e>directly</e>
                        involved with the installation and base configuration of any Gentoo Linux system.
                        To date, our critical documents are: </p>

                                <ul>
                                <li>All of the Gentoo Linux Installation Guides</li>
                                <li>The Desktop Configuration Guide</li>
                                <li>The official Gentoo Linux FAQ</li>
                                <li>The Gentoo Linux Security Guide</li>
                                <li>Any Portage Documentation</li>
                                </ul>

                        <p><b>Non-critical</b> documentation includes all documentation not specifically defined
                        as Critical Documentation. </p>
                        
                        </body>
                </section>
        </chapter>

<chapter>
        <title>Documentation Team Organization</title>
                <section>
                        <title>Organization</title>
                        <body>
                        <p>The Gentoo Linux Documentation team is split into three teams that operate
                        in complete cooperation with eachother. The Documentation team is divided into
                        these three categories:
                        </p>

                        <p><b>Technical Writers: </b>The technical writers' function is to completely 
                        document every aspect of Gentoo Linux. The writers will periodically be given
                        assignments by the Senior Developers, and those assignments are to take precedence
                        over any other Gentoo Linux development work. Although the writers' work is
                        ultimately proofed by the <b>Editing Team</b>, the writers <e>will still</e>
                        proof their own work before submitting it to the <i>gentoo-docs-review@gentoo.org</i>
                        mailing list and the <b>Editing Team</b> All technical writers must be subscribed to the
                        <i>gentoo-docs-review@gentoo.org</i> mailing list.</p>

                        <p><b>Editors/ Proofreaders: </b>The editors are in charge of editing and proofing
                        all changes to the Gentoo Linux Documentation. No change can be made unless it is
                        verified to be grammatically and syntactically correct by an Editor. The Editors
                        must make absolutely sure that <e>all</e> documentation going live on the website
                        is as professional and grammatically correct as possible. All Editors must
                        be subscribed to the <i>gentoo-docs-review@gentoo.org</i> mailing list.</p>

                        <p><b>Translators: </b>Due to the special nature of translations, the translators
                        are broken into their own team. Each language will have a lead Developer which will
                        serve as the Editor and CVS publisher. Once the lead translator has deemed that
                        a translation is ready to go live on the documentation index page, they may add it.
                        After the translation is added, a notice must be sent to the <i>gentoo-docs-review@gentoo.org</i>
                        mailing list.</p>
                        </body>
                </section>
</chapter>

<chapter>
        <title>English Developer Guidelines</title>
                <section>
                        <title>QA Process</title>
                        <body>
                        
                        <p>The English developer's job is <e>extremely</e> important, as all translations have their roots
                        in our English documentation. So, it is imperative that the process described below is followed quite
                        pedantically. 
                        </p>

                        <p>If not done already, the following documents need to be read before continuing:
                        </p>

                        <ul>
                                <li><uri link="http://www.gentoo.org/doc/en/xml-guide.xml">The Gentoo Linux XML Guide</uri></li>
                        </ul>

                        <p>The Gentoo Linux Documentation process can be broken down into several parts:
                        </p>
                        
                        <p><b>The first step to submitting a new document or changing an existing document</b>
                        is filing a bug on our <uri link="http://bugs.gentoo.org">Bug System</uri>. This serves
                        as a notification to other developers and users alike that there is a work in process.
                        If there is already a bug in the database that requests a change to the documentation,
                        a new bug does not have to be filed.
                        </p>

                        <p><b>When the proposed new document or change is completed</b>, two courses of action can
                        be taken: </p>

                        <p>If the change/ bugfix is technical in nature, the revised document, along with its associated
                        bug number, must be posted to the <i>gentoo-docs-review@gentoo.org</i> mailinglist for technical
                        review. This step is incredibly important, as it ensures the technical accuracy of our documentation.
                        The document in question <e>cannot</e> be committed to CVS unless it is submitted for review.</p>

                        <p>If the change/ bugfix is grammatical or syntactical in nature, all that is needed is a short note
                        to <i>gentoo-docs-review@gentoo.org</i> stating the bug number if applicable, and the fix. </p>
                        
                        <p><b>Once the document is in CVS</b>, a Senior Developer will be notified, and the Document will
                        be posted to the live document index page. </p>

                </body>
        </section>
</chapter>


<chapter>
        <title>Translator Guidelines</title>
                <section>
                        <title>QA Process</title>
                        <body>
                        
                        <p>Translators will follow the English Developer's QA process, but with the following exceptions:
                        </p>

                        <p><b>Each language will have a translation team, with an Offical Gentoo Linux Translator</b> as their head.
                        All translations will be filtered through this lead person. The lead translator will make certain that the
                        translated documents are grammatically and syntactically perfect. The lead translator will have limited CVS 
                        access which will enable them to commit documents in a timely manner. </p>
                        
                        <p>If not done already, the following documents need to be read before continuing:
                        </p>

                        <ul>
                                <li><uri link="http://www.gentoo.org/doc/en/xml-guide.xml">The Gentoo Linux XML Guide</uri></li>
                        </ul>
                        <p>The translator's QA process is as follows:</p>

                        <p><b>The first step to submitting a new document or changing an existing document</b>
                        is filing a bug on our <uri link="http://bugs.gentoo.org">Bug System</uri>. This serves
                        as a notification to other developers and users alike that there is a work in process.
                        If there is already a bug in the database that requests a change to the documentation,
                        a new bug does not have to be filed. </p>

                        <p><b>When the proposed new document or change is completed</b>, a notification is to be sent to the
                        translation lead, and the translation lead is to make positively sure that the translated document is
                        perfect in every way.</p>

                        <p><b>Once the document and or change is carefully edited by the lead translator</b>, it can be moved
                        into CVS. </p>

                        <p><b>Once the document is in CVS</b>, a Senior Developer will be notified, and the Document will
                        be posted to the live document index page. </p>
                        </body>
                </section>
</chapter>
                        
<chapter>
        <title>Documentation Contact List</title>
                <section>
                <title>Contact List</title>

                <body>

                <p>If you have any questions, please consult the appropriate person:
                </p>

                <table>
                <tr><th>IRC Nick</th><th>Real Name</th><th>Duties</th></tr>
                <tr><ti>ZhEN</ti><ti><mail link="zhen@gentoo.org">John P. Davis</mail></ti><ti>Documentation Coordinator</ti></tr>
                <tr><ti>stocke2</ti><ti><mail link="stocke2@gentoo.org">Eric Stockbridge</mail></ti><ti>Website</ti></tr>
                <tr><ti>rajiv</ti><ti><mail link="rajiv@gentoo.org">Rajiv</mail></ti><ti>PPC Documentation/ Website</ti></tr>
                <tr><ti>nakano</ti><ti><mail link="nakano@gentoo.org">Masatomo Nakano</mail></ti><ti>Japanese Documentation</ti></tr>
                <tr><ti>seo</ti><ti><mail link="seo@gentoo.org">Jungmin Seo</mail></ti><ti>Bug fixing/Korean Docs</ti></tr>
                <tr><ti>BaSS</ti><ti><mail link="bass@gentoo.org">BaSS</mail></ti><ti>Spanish Documentation</ti></tr>
        <tr><ti>SwifT</ti><ti><mail link="swift@gentoo.org">Sven Vermeulen</mail></ti><ti>Bug Fixing/Dutch Documentation</ti></tr>
        <tr><ti>george</ti><ti><mail link="george@gentoo.org">George Shapovalov</mail></ti><ti>Russian Documentation</ti></tr>
                <tr><ti>Pylon</ti><ti><mail link="pylon@gentoo.org">Lars Weiler</mail></ti><ti>German Documentation</ti></tr>
        <tr><ti>Arachne</ti><ti><mail link="arachne@gentoo.org">Guillaume Morin</mail></ti><ti>French Documentation</ti></tr>
                </table>

                </body>
        </section>
</chapter>

</guide>
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>