en/glep/glep-0051.html

<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<!--
This HTML is auto-generated.  DO NOT EDIT THIS FILE!  If you are writing a new
PEP, see http://www.python.org/peps/pep-0001.html for instructions and links
to templates.  DO NOT USE THIS HTML FILE AS YOUR TEMPLATE!
-->
<head>
  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
  <meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
  <title>GLEP 51 -- Gentoo Knowledge Base</title>
  <style type="text/css">

/*
:Author: David Goodger
:Contact: goodger@users.sourceforge.net
:date: $Date: 2003/06/02 17:03:08 $
:version: $Revision: 1.1 $
:copyright: This stylesheet has been placed in the public domain.

Default cascading style sheet for the PEP HTML output of Docutils.
*/

.first {
  margin-top: 0 }

.last {
  margin-bottom: 0 }

.navigation {
  width: 100% ;
  background: #cc99ff ;
  margin-top: 0px ;
  margin-bottom: 0px }

.navigation .navicon {
  width: 150px ;
  height: 35px }

.navigation .textlinks {
  padding-left: 1em ;
  text-align: left }

.navigation td, .navigation th {
  padding-left: 0em ;
  padding-right: 0em ;
  vertical-align: middle }

.rfc2822 {
  margin-top: 0.5em ;
  margin-left: 0.5em ;
  margin-right: 0.5em ;
  margin-bottom: 0em }

.rfc2822 td {
  text-align: left }

.rfc2822 th.field-name {
  text-align: right ;
  font-family: sans-serif ;
  padding-right: 0.5em ;
  font-weight: bold ;
  margin-bottom: 0em }

a.toc-backref {
  text-decoration: none ;
  color: black }

body {
  margin: 0px ;
  margin-bottom: 1em ;
  padding: 0px }

dd {
  margin-bottom: 0.5em }

div.section {
  margin-left: 1em ;
  margin-right: 1em ;
  margin-bottom: 1.5em }

div.section div.section {
  margin-left: 0em ;
  margin-right: 0em ;
  margin-top: 1.5em }

div.abstract {
  margin: 2em 5em }

div.abstract p.topic-title {
  font-weight: bold ;
  text-align: center }

div.attention, div.caution, div.danger, div.error, div.hint,
div.important, div.note, div.tip, div.warning {
  margin: 2em ;
  border: medium outset ;
  padding: 1em }

div.attention p.admonition-title, div.caution p.admonition-title,
div.danger p.admonition-title, div.error p.admonition-title,
div.warning p.admonition-title {
  color: red ;
  font-weight: bold ;
  font-family: sans-serif }

div.hint p.admonition-title, div.important p.admonition-title,
div.note p.admonition-title, div.tip p.admonition-title {
  font-weight: bold ;
  font-family: sans-serif }

div.figure {
  margin-left: 2em }

div.footer, div.header {
  font-size: smaller }

div.footer {
  margin-left: 1em ;
  margin-right: 1em }

div.system-messages {
  margin: 5em }

div.system-messages h1 {
  color: red }

div.system-message {
  border: medium outset ;
  padding: 1em }

div.system-message p.system-message-title {
  color: red ;
  font-weight: bold }

div.topic {
  margin: 2em }

h1 {
  font-family: sans-serif ;
  font-size: large }

h2 {
  font-family: sans-serif ;
  font-size: medium }

h3 {
  font-family: sans-serif ;
  font-size: small }

h4 {
  font-family: sans-serif ;
  font-style: italic ;
  font-size: small }

h5 {
  font-family: sans-serif;
  font-size: x-small }

h6 {
  font-family: sans-serif;
  font-style: italic ;
  font-size: x-small }

.section hr {
  width: 75% }

ol.simple, ul.simple {
  margin-bottom: 1em }

ol.arabic {
  list-style: decimal }

ol.loweralpha {
  list-style: lower-alpha }

ol.upperalpha {
  list-style: upper-alpha }

ol.lowerroman {
  list-style: lower-roman }

ol.upperroman {
  list-style: upper-roman }

p.caption {
  font-style: italic }

p.credits {
  font-style: italic ;
  font-size: smaller }

p.label {
  white-space: nowrap }

p.topic-title {
  font-family: sans-serif ;
  font-weight: bold }

pre.line-block {
  font-family: serif ;
  font-size: 100% }

pre.literal-block, pre.doctest-block {
  margin-left: 2em ;
  margin-right: 2em ;
  background-color: #eeeeee }

span.classifier {
  font-family: sans-serif ;
  font-style: oblique }

span.classifier-delimiter {
  font-family: sans-serif ;
  font-weight: bold }

span.interpreted {
  font-family: sans-serif }

span.option-argument {
  font-style: italic }

span.pre {
  white-space: pre }

span.problematic {
  color: red }

table {
  margin-top: 0.5em ;
  margin-bottom: 0.5em }

td, th {
  padding-left: 0.5em ;
  padding-right: 0.5em ;
  vertical-align: top }

td.num {
  text-align: right }

th.field-name {
  font-weight: bold ;
  text-align: left ;
  white-space: nowrap }

h1 tt, h2 tt, h3 tt, h4 tt, h5 tt, h6 tt {
  font-size: 100% }

tt {
  background-color: #eeeeee }

ul.auto-toc {
  list-style-type: none }

</style>
</head>
<body bgcolor="white">
<table class="navigation" cellpadding="0" cellspacing="0"
       width="100%" border="0">
<tr><td class="navicon" width="150" height="35">
<a href="http://www.gentoo.org/" title="Gentoo Linux Home Page">
<img src="http://www.gentoo.org/images/gentoo-new.gif" alt="[Gentoo]"
 border="0" width="150" height="35" /></a></td>
<td class="textlinks" align="left">
[<b><a href="http://www.gentoo.org/">Gentoo Linux Home</a></b>]
[<b><a href="http://www.gentoo.org/peps">GLEP Index</a></b>]
[<b><a href="http://www.gentoo.org/proj/en/glep/glep-0051.txt">GLEP Source</a></b>]
</td></tr></table>
<table class="rfc2822 docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">GLEP:</th><td class="field-body">51</td>
</tr>
<tr class="field"><th class="field-name">Title:</th><td class="field-body">Gentoo Knowledge Base</td>
</tr>
<tr class="field"><th class="field-name">Version:</th><td class="field-body">1.1</td>
</tr>
<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>
</tr>
<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>
</tr>
<tr class="field"><th class="field-name">Status:</th><td class="field-body">Draft</td>
</tr>
<tr class="field"><th class="field-name">Type:</th><td class="field-body">Standards Track</td>
</tr>
<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>
</tr>
<tr class="field"><th class="field-name">Created:</th><td class="field-body">30-May-2006</td>
</tr>
<tr class="field"><th class="field-name">Post-History:</th><td class="field-body">16-Aug-2006</td>
</tr>
</tbody>
</table>
<hr />
<div class="contents topic">
<p class="topic-title first"><a id="contents" name="contents">Contents</a></p>
<ul class="simple">
<li><a class="reference" href="#abstract" id="id2" name="id2">Abstract</a></li>
<li><a class="reference" href="#motivation" id="id3" name="id3">Motivation</a></li>
<li><a class="reference" href="#requirements" id="id4" name="id4">Requirements</a><ul>
<li><a class="reference" href="#search-functionality" id="id5" name="id5">Search functionality</a></li>
<li><a class="reference" href="#content-definition" id="id6" name="id6">Content definition</a></li>
<li><a class="reference" href="#feedback-system" id="id7" name="id7">Feedback system</a></li>
<li><a class="reference" href="#topic-maintenance-system" id="id8" name="id8">Topic maintenance system</a></li>
<li><a class="reference" href="#license" id="id9" name="id9">License</a></li>
</ul>
</li>
<li><a class="reference" href="#frameworks" id="id10" name="id10">Frameworks</a></li>
<li><a class="reference" href="#copyright" id="id11" name="id11">Copyright</a></li>
</ul>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id2" id="abstract" name="abstract">Abstract</a></h1>
<p>To improve the self-healing abilities of the Gentoo users, we have to offer a
repository with specific solutions to specific issues and quick answers to
common questions which aren't global enough to fit within a Gentoo Documentation
Guide. Such a repository can be offered by a Gentoo Knowledge Base.</p>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id3" id="motivation" name="motivation">Motivation</a></h1>
<p>When we look at the software projects today, we find that information has
broadened beyond documentation and the detail level has deepend to an almost
individual, precise answer for every question. It is no longer reasonable to
suggest that documentation is sufficient to succesfully aide users with
exploring the world of software use. Documentation is a (and perhaps even the
most) powerful tool to guide users through complex topics. Yet documentation
mainly focuses on a large reader base. Whenever topics become too detailed, they
become difficult to fit inside a certain hierarchical structure.</p>
<p>Such a structure is required by users who need to find documentation quickly. A
major help is, of course, a search feature that spans all documentation.
However, when hundreds of (seemingly similar yet different) topics are
available, many search technologies fail. Natural language queries often express
more details than a regular, boolean expression, but not that many search
technologies allow such queries.</p>
<p>The Gentoo Knowledge Base is an effort to extend the information Gentoo delivers
with precise answers to specific questions. Each topic in the repository must be
owned by at least one knowledgeable developer, written in a structured manner
and should leave no room for different interpretations. General topics must
provide direct links to the documentation.</p>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id4" id="requirements" name="requirements">Requirements</a></h1>
<div class="section">
<h2><a class="toc-backref" href="#id5" id="search-functionality" name="search-functionality">Search functionality</a></h2>
<p>As one of the major features of a good Knowledge Base, the search engine used
should allow for natural language queries as those are easier for people to
use. However, clear cut 'n paste queries should also prove to be very
effective as many questions rise from error messages.</p>
</div>
<div class="section">
<h2><a class="toc-backref" href="#id6" id="content-definition" name="content-definition">Content definition</a></h2>
<p>The topics with the most content would be the issue-type topics who describe a
certain error and inform the user about the resolution. To make sure these
issues are specific enough (not &quot;how do I fix a build fault&quot;) they must
describe the following aspects thoroughly:</p>
<ul class="simple">
<li>The <em>title</em> describes the issue well enough for most users to quickly find
out if the topic is of interest for them or not. It is also displayed in
the search results</li>
<li>The <em>synopsis</em> gives more detail about the error, such as the full error
message, commands that triggered it or the (mis)behavior of a specific
command</li>
<li>The <em>environment</em> informs the user when the topic applies. If the users'
environment doesn't match this one, the topic isn't valid for him.</li>
<li>In the <em>analysis</em> section, the cause of the error is considered in great
detail to discover the essential flaw that triggered the error. It serves
as an information section for the user to comprehend what went wrong.</li>
<li>To fix the error, the <em>resolution</em> section guides the user through the
necessary steps to resolve the issue.</li>
</ul>
<p>A second type of queries would be small (but interesting) FAQs. These answers
are short and precise, most of the time one or two paragraphs.</p>
<p>Although several topics will be Gentoo specific, we will not limit ourselves
to this. However, we do not add topics that are specific to non-Gentoo
distributions.</p>
</div>
<div class="section">
<h2><a class="toc-backref" href="#id7" id="feedback-system" name="feedback-system">Feedback system</a></h2>
<p>The knowledge base should allow for user feedback. Feedback such as &quot;Does this
answer your question?&quot; is invaluable to improve the search results whereas
&quot;Mark this topic as outdated&quot; helps us keep the knowledge base in good shape.</p>
<p>We might want to consider allowing user comments too: they can add priceless
information to the topic, allowing the maintainer of the topic to update it
with more accurate information.</p>
</div>
<div class="section">
<h2><a class="toc-backref" href="#id8" id="topic-maintenance-system" name="topic-maintenance-system">Topic maintenance system</a></h2>
<p>Each topic should be maintained by a knowledgeable developer. The system must
allow the developer to watch his topics and update them when needed. Of
course, topics related to specific herds should be maintainable by the team
responsible for the herd.</p>
<p>Although not required, revision history would be great :-)</p>
</div>
<div class="section">
<h2><a class="toc-backref" href="#id9" id="license" name="license">License</a></h2>
<p>The content of the knowledge base should be public domain. Everything large
enough to warrant a different license shouldn't be in the knowledge base
anyway.</p>
</div>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id10" id="frameworks" name="frameworks">Frameworks</a></h1>
<p>Based on the requirements, one or more frameworks will be chosen. These should
of course be free software projects; if we can't find any set of frameworks
that adheres to the requirements, the knowledge base project should build one
up until the requirements are met.</p>
<p>We currently do not have any technical requirements on the frameworks, but at
the end the knowledge base should be hosted on official Gentoo hardware and
maintained by the Infrastructure project. As such, the Infrastructure project
has final saying on the frameworks used in the knowledge base.</p>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id11" id="copyright" name="copyright">Copyright</a></h1>
<p>This document has been placed in the public domain.</p>
</div>

</div>
<div class="footer">
<hr class="footer" />
<a class="reference" href="glep-0051.txt">View document source</a>.
Generated on: 2006-10-10 20:23 UTC.
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.

</div>
</body>
</html>
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: 2003/06/02 17:03:08 $
19	:version: $Revision: 1.1 $
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/peps">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 <swift at gentoo.org>,</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 "how do I fix a build fault") 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 "Does this
382	answer your question?" is invaluable to improve the search results whereas
383	"Mark this topic as outdated" 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>