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

Parent Directory Parent Directory | Revision Log Revision Log

Revision 1.4 - (hide annotations) (download) (as text)
Sun Oct 14 17:00:15 2007 UTC (11 years, 5 months ago) by antarus
Branch: MAIN
Changes since 1.3: +8 -255 lines
File MIME type: text/html
the canary on 53 went well, changing the rest

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 antarus 1.4
5 liquidx 1.1 <head>
6     <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
7 g2boojum 1.2 <meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
8 liquidx 1.1 <title>GLEP 51 -- Gentoo Knowledge Base</title>
9 antarus 1.4 <link rel="stylesheet" href="tools/glep.css" type="text/css" />
10 liquidx 1.1 </head>
11     <body bgcolor="white">
12     <table class="navigation" cellpadding="0" cellspacing="0"
13     width="100%" border="0">
14     <tr><td class="navicon" width="150" height="35">
15     <a href="http://www.gentoo.org/" title="Gentoo Linux Home Page">
16     <img src="http://www.gentoo.org/images/gentoo-new.gif" alt="[Gentoo]"
17     border="0" width="150" height="35" /></a></td>
18     <td class="textlinks" align="left">
19     [<b><a href="http://www.gentoo.org/">Gentoo Linux Home</a></b>]
20 antarus 1.4 [<b><a href="http://www.gentoo.org/proj/en/glep">GLEP Index</a></b>]
21 g2boojum 1.2 [<b><a href="http://www.gentoo.org/proj/en/glep/glep-0051.txt">GLEP Source</a></b>]
22 liquidx 1.1 </td></tr></table>
23     <table class="rfc2822 docutils field-list" frame="void" rules="none">
24     <col class="field-name" />
25     <col class="field-body" />
26     <tbody valign="top">
27     <tr class="field"><th class="field-name">GLEP:</th><td class="field-body">51</td>
28     </tr>
29     <tr class="field"><th class="field-name">Title:</th><td class="field-body">Gentoo Knowledge Base</td>
30     </tr>
31 antarus 1.4 <tr class="field"><th class="field-name">Version:</th><td class="field-body">1.2</td>
32 liquidx 1.1 </tr>
33 antarus 1.4 <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">2007/03/26 10:27:50</a></td>
34 liquidx 1.1 </tr>
35     <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>
36     </tr>
37 antarus 1.4 <tr class="field"><th class="field-name">Status:</th><td class="field-body">Withdrawn</td>
38 liquidx 1.1 </tr>
39     <tr class="field"><th class="field-name">Type:</th><td class="field-body">Standards Track</td>
40     </tr>
41 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>
42 liquidx 1.1 </tr>
43     <tr class="field"><th class="field-name">Created:</th><td class="field-body">30-May-2006</td>
44     </tr>
45 antarus 1.4 <tr class="field"><th class="field-name">Post-History:</th><td class="field-body">26-Mar-2007</td>
46 liquidx 1.1 </tr>
47     </tbody>
48     </table>
49     <hr />
50 g2boojum 1.2 <div class="contents topic">
51     <p class="topic-title first"><a id="contents" name="contents">Contents</a></p>
52 liquidx 1.1 <ul class="simple">
53     <li><a class="reference" href="#abstract" id="id2" name="id2">Abstract</a></li>
54     <li><a class="reference" href="#motivation" id="id3" name="id3">Motivation</a></li>
55     <li><a class="reference" href="#requirements" id="id4" name="id4">Requirements</a><ul>
56     <li><a class="reference" href="#search-functionality" id="id5" name="id5">Search functionality</a></li>
57     <li><a class="reference" href="#content-definition" id="id6" name="id6">Content definition</a></li>
58     <li><a class="reference" href="#feedback-system" id="id7" name="id7">Feedback system</a></li>
59     <li><a class="reference" href="#topic-maintenance-system" id="id8" name="id8">Topic maintenance system</a></li>
60     <li><a class="reference" href="#license" id="id9" name="id9">License</a></li>
61     </ul>
62     </li>
63     <li><a class="reference" href="#frameworks" id="id10" name="id10">Frameworks</a></li>
64     <li><a class="reference" href="#copyright" id="id11" name="id11">Copyright</a></li>
65     </ul>
66     </div>
67 g2boojum 1.2 <div class="section">
68     <h1><a class="toc-backref" href="#id2" id="abstract" name="abstract">Abstract</a></h1>
69 liquidx 1.1 <p>To improve the self-healing abilities of the Gentoo users, we have to offer a
70 g2boojum 1.2 repository with specific solutions to specific issues and quick answers to
71 liquidx 1.1 common questions which aren't global enough to fit within a Gentoo Documentation
72     Guide. Such a repository can be offered by a Gentoo Knowledge Base.</p>
73     </div>
74 g2boojum 1.2 <div class="section">
75     <h1><a class="toc-backref" href="#id3" id="motivation" name="motivation">Motivation</a></h1>
76 liquidx 1.1 <p>When we look at the software projects today, we find that information has
77     broadened beyond documentation and the detail level has deepend to an almost
78     individual, precise answer for every question. It is no longer reasonable to
79     suggest that documentation is sufficient to succesfully aide users with
80     exploring the world of software use. Documentation is a (and perhaps even the
81     most) powerful tool to guide users through complex topics. Yet documentation
82     mainly focuses on a large reader base. Whenever topics become too detailed, they
83     become difficult to fit inside a certain hierarchical structure.</p>
84     <p>Such a structure is required by users who need to find documentation quickly. A
85     major help is, of course, a search feature that spans all documentation.
86     However, when hundreds of (seemingly similar yet different) topics are
87     available, many search technologies fail. Natural language queries often express
88     more details than a regular, boolean expression, but not that many search
89     technologies allow such queries.</p>
90     <p>The Gentoo Knowledge Base is an effort to extend the information Gentoo delivers
91     with precise answers to specific questions. Each topic in the repository must be
92     owned by at least one knowledgeable developer, written in a structured manner
93     and should leave no room for different interpretations. General topics must
94     provide direct links to the documentation.</p>
95     </div>
96 g2boojum 1.2 <div class="section">
97     <h1><a class="toc-backref" href="#id4" id="requirements" name="requirements">Requirements</a></h1>
98     <div class="section">
99     <h2><a class="toc-backref" href="#id5" id="search-functionality" name="search-functionality">Search functionality</a></h2>
100 liquidx 1.1 <p>As one of the major features of a good Knowledge Base, the search engine used
101     should allow for natural language queries as those are easier for people to
102     use. However, clear cut 'n paste queries should also prove to be very
103     effective as many questions rise from error messages.</p>
104     </div>
105 g2boojum 1.2 <div class="section">
106     <h2><a class="toc-backref" href="#id6" id="content-definition" name="content-definition">Content definition</a></h2>
107 liquidx 1.1 <p>The topics with the most content would be the issue-type topics who describe a
108     certain error and inform the user about the resolution. To make sure these
109     issues are specific enough (not &quot;how do I fix a build fault&quot;) they must
110     describe the following aspects thoroughly:</p>
111     <ul class="simple">
112     <li>The <em>title</em> describes the issue well enough for most users to quickly find
113     out if the topic is of interest for them or not. It is also displayed in
114     the search results</li>
115     <li>The <em>synopsis</em> gives more detail about the error, such as the full error
116     message, commands that triggered it or the (mis)behavior of a specific
117     command</li>
118     <li>The <em>environment</em> informs the user when the topic applies. If the users'
119     environment doesn't match this one, the topic isn't valid for him.</li>
120     <li>In the <em>analysis</em> section, the cause of the error is considered in great
121     detail to discover the essential flaw that triggered the error. It serves
122     as an information section for the user to comprehend what went wrong.</li>
123     <li>To fix the error, the <em>resolution</em> section guides the user through the
124     necessary steps to resolve the issue.</li>
125     </ul>
126     <p>A second type of queries would be small (but interesting) FAQs. These answers
127     are short and precise, most of the time one or two paragraphs.</p>
128     <p>Although several topics will be Gentoo specific, we will not limit ourselves
129 g2boojum 1.2 to this. However, we do not add topics that are specific to non-Gentoo
130 liquidx 1.1 distributions.</p>
131     </div>
132 g2boojum 1.2 <div class="section">
133     <h2><a class="toc-backref" href="#id7" id="feedback-system" name="feedback-system">Feedback system</a></h2>
134 liquidx 1.1 <p>The knowledge base should allow for user feedback. Feedback such as &quot;Does this
135     answer your question?&quot; is invaluable to improve the search results whereas
136     &quot;Mark this topic as outdated&quot; helps us keep the knowledge base in good shape.</p>
137     <p>We might want to consider allowing user comments too: they can add priceless
138     information to the topic, allowing the maintainer of the topic to update it
139     with more accurate information.</p>
140     </div>
141 g2boojum 1.2 <div class="section">
142     <h2><a class="toc-backref" href="#id8" id="topic-maintenance-system" name="topic-maintenance-system">Topic maintenance system</a></h2>
143 liquidx 1.1 <p>Each topic should be maintained by a knowledgeable developer. The system must
144     allow the developer to watch his topics and update them when needed. Of
145     course, topics related to specific herds should be maintainable by the team
146     responsible for the herd.</p>
147     <p>Although not required, revision history would be great :-)</p>
148     </div>
149 g2boojum 1.2 <div class="section">
150     <h2><a class="toc-backref" href="#id9" id="license" name="license">License</a></h2>
151 liquidx 1.1 <p>The content of the knowledge base should be public domain. Everything large
152     enough to warrant a different license shouldn't be in the knowledge base
153     anyway.</p>
154     </div>
155     </div>
156 g2boojum 1.2 <div class="section">
157     <h1><a class="toc-backref" href="#id10" id="frameworks" name="frameworks">Frameworks</a></h1>
158 liquidx 1.1 <p>Based on the requirements, one or more frameworks will be chosen. These should
159     of course be free software projects; if we can't find any set of frameworks
160     that adheres to the requirements, the knowledge base project should build one
161     up until the requirements are met.</p>
162     <p>We currently do not have any technical requirements on the frameworks, but at
163     the end the knowledge base should be hosted on official Gentoo hardware and
164     maintained by the Infrastructure project. As such, the Infrastructure project
165     has final saying on the frameworks used in the knowledge base.</p>
166     </div>
167 g2boojum 1.2 <div class="section">
168     <h1><a class="toc-backref" href="#id11" id="copyright" name="copyright">Copyright</a></h1>
169 liquidx 1.1 <p>This document has been placed in the public domain.</p>
170     </div>
172     </div>
173     <div class="footer">
174 g2boojum 1.2 <hr class="footer" />
175 liquidx 1.1 <a class="reference" href="glep-0051.txt">View document source</a>.
176 antarus 1.4 Generated on: 2007-10-13 13:39 UTC.
177 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.
178 g2boojum 1.2
179 liquidx 1.1 </div>
180     </body>
181     </html>

  ViewVC Help
Powered by ViewVC 1.1.20