/[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 - (hide annotations) (download) (as text)
Thu Jan 25 03:25:53 2007 UTC (7 years, 2 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 liquidx 1.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 g2boojum 1.2 <meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
12 liquidx 1.1 <title>GLEP 51 -- Gentoo Knowledge Base</title>
13 g2boojum 1.2 <style type="text/css">
14    
15     /*
16     :Author: David Goodger
17     :Contact: goodger@users.sourceforge.net
18 antarus 1.3 :date: $Date: 2006/10/10 20:25:14 $
19     :version: $Revision: 1.2 $
20 g2boojum 1.2 :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 liquidx 1.1 </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 antarus 1.3 [<b><a href="http://www.gentoo.org/proj/en/glep/">GLEP Index</a></b>]
268 g2boojum 1.2 [<b><a href="http://www.gentoo.org/proj/en/glep/glep-0051.txt">GLEP Source</a></b>]
269 liquidx 1.1 </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 g2boojum 1.2 <tr class="field"><th class="field-name">Version:</th><td class="field-body">1.1</td>
279 liquidx 1.1 </tr>
280 g2boojum 1.2 <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 liquidx 1.1 </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 g2boojum 1.2 <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 liquidx 1.1 </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 g2boojum 1.2 <div class="contents topic">
298     <p class="topic-title first"><a id="contents" name="contents">Contents</a></p>
299 liquidx 1.1 <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 g2boojum 1.2 <div class="section">
315     <h1><a class="toc-backref" href="#id2" id="abstract" name="abstract">Abstract</a></h1>
316 liquidx 1.1 <p>To improve the self-healing abilities of the Gentoo users, we have to offer a
317 g2boojum 1.2 repository with specific solutions to specific issues and quick answers to
318 liquidx 1.1 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 g2boojum 1.2 <div class="section">
322     <h1><a class="toc-backref" href="#id3" id="motivation" name="motivation">Motivation</a></h1>
323 liquidx 1.1 <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 g2boojum 1.2 <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 liquidx 1.1 <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 g2boojum 1.2 <div class="section">
353     <h2><a class="toc-backref" href="#id6" id="content-definition" name="content-definition">Content definition</a></h2>
354 liquidx 1.1 <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 g2boojum 1.2 to this. However, we do not add topics that are specific to non-Gentoo
377 liquidx 1.1 distributions.</p>
378     </div>
379 g2boojum 1.2 <div class="section">
380     <h2><a class="toc-backref" href="#id7" id="feedback-system" name="feedback-system">Feedback system</a></h2>
381 liquidx 1.1 <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 g2boojum 1.2 <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 liquidx 1.1 <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 g2boojum 1.2 <div class="section">
397     <h2><a class="toc-backref" href="#id9" id="license" name="license">License</a></h2>
398 liquidx 1.1 <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 g2boojum 1.2 <div class="section">
404     <h1><a class="toc-backref" href="#id10" id="frameworks" name="frameworks">Frameworks</a></h1>
405 liquidx 1.1 <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 g2boojum 1.2 <div class="section">
415     <h1><a class="toc-backref" href="#id11" id="copyright" name="copyright">Copyright</a></h1>
416 liquidx 1.1 <p>This document has been placed in the public domain.</p>
417     </div>
418    
419     </div>
420     <div class="footer">
421 g2boojum 1.2 <hr class="footer" />
422 liquidx 1.1 <a class="reference" href="glep-0051.txt">View document source</a>.
423 g2boojum 1.2 Generated on: 2006-10-10 20:23 UTC.
424 liquidx 1.1 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 g2boojum 1.2
426 liquidx 1.1 </div>
427     </body>
428     </html>

  ViewVC Help
Powered by ViewVC 1.1.20