/[gentoo]/xml/htdocs/proj/en/glep/glep-0051.html
Gentoo

Contents of /xml/htdocs/proj/en/glep/glep-0051.html

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.3 - (show annotations) (download) (as text)
Thu Jan 25 03:25:53 2007 UTC (7 years, 7 months ago) by antarus
Branch: MAIN
Changes since 1.2: +3 -3 lines
File MIME type: text/html
Fix headers in all current gleps

1 <?xml version="1.0" encoding="utf-8" ?>
2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
4 <!--
5 This HTML is auto-generated. DO NOT EDIT THIS FILE! If you are writing a new
6 PEP, see http://www.python.org/peps/pep-0001.html for instructions and links
7 to templates. DO NOT USE THIS HTML FILE AS YOUR TEMPLATE!
8 -->
9 <head>
10 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
11 <meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
12 <title>GLEP 51 -- Gentoo Knowledge Base</title>
13 <style type="text/css">
14
15 /*
16 :Author: David Goodger
17 :Contact: goodger@users.sourceforge.net
18 :date: $Date: 2006/10/10 20:25:14 $
19 :version: $Revision: 1.2 $
20 :copyright: This stylesheet has been placed in the public domain.
21
22 Default cascading style sheet for the PEP HTML output of Docutils.
23 */
24
25 .first {
26 margin-top: 0 }
27
28 .last {
29 margin-bottom: 0 }
30
31 .navigation {
32 width: 100% ;
33 background: #cc99ff ;
34 margin-top: 0px ;
35 margin-bottom: 0px }
36
37 .navigation .navicon {
38 width: 150px ;
39 height: 35px }
40
41 .navigation .textlinks {
42 padding-left: 1em ;
43 text-align: left }
44
45 .navigation td, .navigation th {
46 padding-left: 0em ;
47 padding-right: 0em ;
48 vertical-align: middle }
49
50 .rfc2822 {
51 margin-top: 0.5em ;
52 margin-left: 0.5em ;
53 margin-right: 0.5em ;
54 margin-bottom: 0em }
55
56 .rfc2822 td {
57 text-align: left }
58
59 .rfc2822 th.field-name {
60 text-align: right ;
61 font-family: sans-serif ;
62 padding-right: 0.5em ;
63 font-weight: bold ;
64 margin-bottom: 0em }
65
66 a.toc-backref {
67 text-decoration: none ;
68 color: black }
69
70 body {
71 margin: 0px ;
72 margin-bottom: 1em ;
73 padding: 0px }
74
75 dd {
76 margin-bottom: 0.5em }
77
78 div.section {
79 margin-left: 1em ;
80 margin-right: 1em ;
81 margin-bottom: 1.5em }
82
83 div.section div.section {
84 margin-left: 0em ;
85 margin-right: 0em ;
86 margin-top: 1.5em }
87
88 div.abstract {
89 margin: 2em 5em }
90
91 div.abstract p.topic-title {
92 font-weight: bold ;
93 text-align: center }
94
95 div.attention, div.caution, div.danger, div.error, div.hint,
96 div.important, div.note, div.tip, div.warning {
97 margin: 2em ;
98 border: medium outset ;
99 padding: 1em }
100
101 div.attention p.admonition-title, div.caution p.admonition-title,
102 div.danger p.admonition-title, div.error p.admonition-title,
103 div.warning p.admonition-title {
104 color: red ;
105 font-weight: bold ;
106 font-family: sans-serif }
107
108 div.hint p.admonition-title, div.important p.admonition-title,
109 div.note p.admonition-title, div.tip p.admonition-title {
110 font-weight: bold ;
111 font-family: sans-serif }
112
113 div.figure {
114 margin-left: 2em }
115
116 div.footer, div.header {
117 font-size: smaller }
118
119 div.footer {
120 margin-left: 1em ;
121 margin-right: 1em }
122
123 div.system-messages {
124 margin: 5em }
125
126 div.system-messages h1 {
127 color: red }
128
129 div.system-message {
130 border: medium outset ;
131 padding: 1em }
132
133 div.system-message p.system-message-title {
134 color: red ;
135 font-weight: bold }
136
137 div.topic {
138 margin: 2em }
139
140 h1 {
141 font-family: sans-serif ;
142 font-size: large }
143
144 h2 {
145 font-family: sans-serif ;
146 font-size: medium }
147
148 h3 {
149 font-family: sans-serif ;
150 font-size: small }
151
152 h4 {
153 font-family: sans-serif ;
154 font-style: italic ;
155 font-size: small }
156
157 h5 {
158 font-family: sans-serif;
159 font-size: x-small }
160
161 h6 {
162 font-family: sans-serif;
163 font-style: italic ;
164 font-size: x-small }
165
166 .section hr {
167 width: 75% }
168
169 ol.simple, ul.simple {
170 margin-bottom: 1em }
171
172 ol.arabic {
173 list-style: decimal }
174
175 ol.loweralpha {
176 list-style: lower-alpha }
177
178 ol.upperalpha {
179 list-style: upper-alpha }
180
181 ol.lowerroman {
182 list-style: lower-roman }
183
184 ol.upperroman {
185 list-style: upper-roman }
186
187 p.caption {
188 font-style: italic }
189
190 p.credits {
191 font-style: italic ;
192 font-size: smaller }
193
194 p.label {
195 white-space: nowrap }
196
197 p.topic-title {
198 font-family: sans-serif ;
199 font-weight: bold }
200
201 pre.line-block {
202 font-family: serif ;
203 font-size: 100% }
204
205 pre.literal-block, pre.doctest-block {
206 margin-left: 2em ;
207 margin-right: 2em ;
208 background-color: #eeeeee }
209
210 span.classifier {
211 font-family: sans-serif ;
212 font-style: oblique }
213
214 span.classifier-delimiter {
215 font-family: sans-serif ;
216 font-weight: bold }
217
218 span.interpreted {
219 font-family: sans-serif }
220
221 span.option-argument {
222 font-style: italic }
223
224 span.pre {
225 white-space: pre }
226
227 span.problematic {
228 color: red }
229
230 table {
231 margin-top: 0.5em ;
232 margin-bottom: 0.5em }
233
234 td, th {
235 padding-left: 0.5em ;
236 padding-right: 0.5em ;
237 vertical-align: top }
238
239 td.num {
240 text-align: right }
241
242 th.field-name {
243 font-weight: bold ;
244 text-align: left ;
245 white-space: nowrap }
246
247 h1 tt, h2 tt, h3 tt, h4 tt, h5 tt, h6 tt {
248 font-size: 100% }
249
250 tt {
251 background-color: #eeeeee }
252
253 ul.auto-toc {
254 list-style-type: none }
255
256 </style>
257 </head>
258 <body bgcolor="white">
259 <table class="navigation" cellpadding="0" cellspacing="0"
260 width="100%" border="0">
261 <tr><td class="navicon" width="150" height="35">
262 <a href="http://www.gentoo.org/" title="Gentoo Linux Home Page">
263 <img src="http://www.gentoo.org/images/gentoo-new.gif" alt="[Gentoo]"
264 border="0" width="150" height="35" /></a></td>
265 <td class="textlinks" align="left">
266 [<b><a href="http://www.gentoo.org/">Gentoo Linux Home</a></b>]
267 [<b><a href="http://www.gentoo.org/proj/en/glep/">GLEP Index</a></b>]
268 [<b><a href="http://www.gentoo.org/proj/en/glep/glep-0051.txt">GLEP Source</a></b>]
269 </td></tr></table>
270 <table class="rfc2822 docutils field-list" frame="void" rules="none">
271 <col class="field-name" />
272 <col class="field-body" />
273 <tbody valign="top">
274 <tr class="field"><th class="field-name">GLEP:</th><td class="field-body">51</td>
275 </tr>
276 <tr class="field"><th class="field-name">Title:</th><td class="field-body">Gentoo Knowledge Base</td>
277 </tr>
278 <tr class="field"><th class="field-name">Version:</th><td class="field-body">1.1</td>
279 </tr>
280 <tr class="field"><th class="field-name">Last-Modified:</th><td class="field-body"><a class="reference" href="http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/proj/en/glep/glep-0051.txt?cvsroot=gentoo">2006/08/16 19:25:14</a></td>
281 </tr>
282 <tr class="field"><th class="field-name">Author:</th><td class="field-body">Sven Vermeulen &lt;swift&#32;&#97;t&#32;gentoo.org&gt;,</td>
283 </tr>
284 <tr class="field"><th class="field-name">Status:</th><td class="field-body">Draft</td>
285 </tr>
286 <tr class="field"><th class="field-name">Type:</th><td class="field-body">Standards Track</td>
287 </tr>
288 <tr class="field"><th class="field-name">Content-Type:</th><td class="field-body"><a class="reference" href="glep-0002.html">text/x-rst</a></td>
289 </tr>
290 <tr class="field"><th class="field-name">Created:</th><td class="field-body">30-May-2006</td>
291 </tr>
292 <tr class="field"><th class="field-name">Post-History:</th><td class="field-body">16-Aug-2006</td>
293 </tr>
294 </tbody>
295 </table>
296 <hr />
297 <div class="contents topic">
298 <p class="topic-title first"><a id="contents" name="contents">Contents</a></p>
299 <ul class="simple">
300 <li><a class="reference" href="#abstract" id="id2" name="id2">Abstract</a></li>
301 <li><a class="reference" href="#motivation" id="id3" name="id3">Motivation</a></li>
302 <li><a class="reference" href="#requirements" id="id4" name="id4">Requirements</a><ul>
303 <li><a class="reference" href="#search-functionality" id="id5" name="id5">Search functionality</a></li>
304 <li><a class="reference" href="#content-definition" id="id6" name="id6">Content definition</a></li>
305 <li><a class="reference" href="#feedback-system" id="id7" name="id7">Feedback system</a></li>
306 <li><a class="reference" href="#topic-maintenance-system" id="id8" name="id8">Topic maintenance system</a></li>
307 <li><a class="reference" href="#license" id="id9" name="id9">License</a></li>
308 </ul>
309 </li>
310 <li><a class="reference" href="#frameworks" id="id10" name="id10">Frameworks</a></li>
311 <li><a class="reference" href="#copyright" id="id11" name="id11">Copyright</a></li>
312 </ul>
313 </div>
314 <div class="section">
315 <h1><a class="toc-backref" href="#id2" id="abstract" name="abstract">Abstract</a></h1>
316 <p>To improve the self-healing abilities of the Gentoo users, we have to offer a
317 repository with specific solutions to specific issues and quick answers to
318 common questions which aren't global enough to fit within a Gentoo Documentation
319 Guide. Such a repository can be offered by a Gentoo Knowledge Base.</p>
320 </div>
321 <div class="section">
322 <h1><a class="toc-backref" href="#id3" id="motivation" name="motivation">Motivation</a></h1>
323 <p>When we look at the software projects today, we find that information has
324 broadened beyond documentation and the detail level has deepend to an almost
325 individual, precise answer for every question. It is no longer reasonable to
326 suggest that documentation is sufficient to succesfully aide users with
327 exploring the world of software use. Documentation is a (and perhaps even the
328 most) powerful tool to guide users through complex topics. Yet documentation
329 mainly focuses on a large reader base. Whenever topics become too detailed, they
330 become difficult to fit inside a certain hierarchical structure.</p>
331 <p>Such a structure is required by users who need to find documentation quickly. A
332 major help is, of course, a search feature that spans all documentation.
333 However, when hundreds of (seemingly similar yet different) topics are
334 available, many search technologies fail. Natural language queries often express
335 more details than a regular, boolean expression, but not that many search
336 technologies allow such queries.</p>
337 <p>The Gentoo Knowledge Base is an effort to extend the information Gentoo delivers
338 with precise answers to specific questions. Each topic in the repository must be
339 owned by at least one knowledgeable developer, written in a structured manner
340 and should leave no room for different interpretations. General topics must
341 provide direct links to the documentation.</p>
342 </div>
343 <div class="section">
344 <h1><a class="toc-backref" href="#id4" id="requirements" name="requirements">Requirements</a></h1>
345 <div class="section">
346 <h2><a class="toc-backref" href="#id5" id="search-functionality" name="search-functionality">Search functionality</a></h2>
347 <p>As one of the major features of a good Knowledge Base, the search engine used
348 should allow for natural language queries as those are easier for people to
349 use. However, clear cut 'n paste queries should also prove to be very
350 effective as many questions rise from error messages.</p>
351 </div>
352 <div class="section">
353 <h2><a class="toc-backref" href="#id6" id="content-definition" name="content-definition">Content definition</a></h2>
354 <p>The topics with the most content would be the issue-type topics who describe a
355 certain error and inform the user about the resolution. To make sure these
356 issues are specific enough (not &quot;how do I fix a build fault&quot;) they must
357 describe the following aspects thoroughly:</p>
358 <ul class="simple">
359 <li>The <em>title</em> describes the issue well enough for most users to quickly find
360 out if the topic is of interest for them or not. It is also displayed in
361 the search results</li>
362 <li>The <em>synopsis</em> gives more detail about the error, such as the full error
363 message, commands that triggered it or the (mis)behavior of a specific
364 command</li>
365 <li>The <em>environment</em> informs the user when the topic applies. If the users'
366 environment doesn't match this one, the topic isn't valid for him.</li>
367 <li>In the <em>analysis</em> section, the cause of the error is considered in great
368 detail to discover the essential flaw that triggered the error. It serves
369 as an information section for the user to comprehend what went wrong.</li>
370 <li>To fix the error, the <em>resolution</em> section guides the user through the
371 necessary steps to resolve the issue.</li>
372 </ul>
373 <p>A second type of queries would be small (but interesting) FAQs. These answers
374 are short and precise, most of the time one or two paragraphs.</p>
375 <p>Although several topics will be Gentoo specific, we will not limit ourselves
376 to this. However, we do not add topics that are specific to non-Gentoo
377 distributions.</p>
378 </div>
379 <div class="section">
380 <h2><a class="toc-backref" href="#id7" id="feedback-system" name="feedback-system">Feedback system</a></h2>
381 <p>The knowledge base should allow for user feedback. Feedback such as &quot;Does this
382 answer your question?&quot; is invaluable to improve the search results whereas
383 &quot;Mark this topic as outdated&quot; helps us keep the knowledge base in good shape.</p>
384 <p>We might want to consider allowing user comments too: they can add priceless
385 information to the topic, allowing the maintainer of the topic to update it
386 with more accurate information.</p>
387 </div>
388 <div class="section">
389 <h2><a class="toc-backref" href="#id8" id="topic-maintenance-system" name="topic-maintenance-system">Topic maintenance system</a></h2>
390 <p>Each topic should be maintained by a knowledgeable developer. The system must
391 allow the developer to watch his topics and update them when needed. Of
392 course, topics related to specific herds should be maintainable by the team
393 responsible for the herd.</p>
394 <p>Although not required, revision history would be great :-)</p>
395 </div>
396 <div class="section">
397 <h2><a class="toc-backref" href="#id9" id="license" name="license">License</a></h2>
398 <p>The content of the knowledge base should be public domain. Everything large
399 enough to warrant a different license shouldn't be in the knowledge base
400 anyway.</p>
401 </div>
402 </div>
403 <div class="section">
404 <h1><a class="toc-backref" href="#id10" id="frameworks" name="frameworks">Frameworks</a></h1>
405 <p>Based on the requirements, one or more frameworks will be chosen. These should
406 of course be free software projects; if we can't find any set of frameworks
407 that adheres to the requirements, the knowledge base project should build one
408 up until the requirements are met.</p>
409 <p>We currently do not have any technical requirements on the frameworks, but at
410 the end the knowledge base should be hosted on official Gentoo hardware and
411 maintained by the Infrastructure project. As such, the Infrastructure project
412 has final saying on the frameworks used in the knowledge base.</p>
413 </div>
414 <div class="section">
415 <h1><a class="toc-backref" href="#id11" id="copyright" name="copyright">Copyright</a></h1>
416 <p>This document has been placed in the public domain.</p>
417 </div>
418
419 </div>
420 <div class="footer">
421 <hr class="footer" />
422 <a class="reference" href="glep-0051.txt">View document source</a>.
423 Generated on: 2006-10-10 20:23 UTC.
424 Generated by <a class="reference" href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source.
425
426 </div>
427 </body>
428 </html>

  ViewVC Help
Powered by ViewVC 1.1.20