1 |
GLEP: 51 |
2 |
Title: Gentoo Knowledge Base |
3 |
Version: $Revision: 1.1 $ |
4 |
Last-Modified: $Date: 2006/08/16 19:25:14 $ |
5 |
Author: Sven Vermeulen <swift@gentoo.org>, |
6 |
Status: Withdrawn |
7 |
Type: Standards Track |
8 |
Content-Type: text/x-rst |
9 |
Created: 30-May-2006 |
10 |
Post-History: 26-Mar-2007 |
11 |
|
12 |
|
13 |
Abstract |
14 |
======== |
15 |
|
16 |
To improve the self-healing abilities of the Gentoo users, we have to offer a |
17 |
repository with specific solutions to specific issues and quick answers to |
18 |
common questions which aren't global enough to fit within a Gentoo Documentation |
19 |
Guide. Such a repository can be offered by a Gentoo Knowledge Base. |
20 |
|
21 |
|
22 |
Motivation |
23 |
========== |
24 |
|
25 |
When we look at the software projects today, we find that information has |
26 |
broadened beyond documentation and the detail level has deepend to an almost |
27 |
individual, precise answer for every question. It is no longer reasonable to |
28 |
suggest that documentation is sufficient to succesfully aide users with |
29 |
exploring the world of software use. Documentation is a (and perhaps even the |
30 |
most) powerful tool to guide users through complex topics. Yet documentation |
31 |
mainly focuses on a large reader base. Whenever topics become too detailed, they |
32 |
become difficult to fit inside a certain hierarchical structure. |
33 |
|
34 |
Such a structure is required by users who need to find documentation quickly. A |
35 |
major help is, of course, a search feature that spans all documentation. |
36 |
However, when hundreds of (seemingly similar yet different) topics are |
37 |
available, many search technologies fail. Natural language queries often express |
38 |
more details than a regular, boolean expression, but not that many search |
39 |
technologies allow such queries. |
40 |
|
41 |
The Gentoo Knowledge Base is an effort to extend the information Gentoo delivers |
42 |
with precise answers to specific questions. Each topic in the repository must be |
43 |
owned by at least one knowledgeable developer, written in a structured manner |
44 |
and should leave no room for different interpretations. General topics must |
45 |
provide direct links to the documentation. |
46 |
|
47 |
|
48 |
Requirements |
49 |
============= |
50 |
|
51 |
Search functionality |
52 |
-------------------- |
53 |
|
54 |
As one of the major features of a good Knowledge Base, the search engine used |
55 |
should allow for natural language queries as those are easier for people to |
56 |
use. However, clear cut 'n paste queries should also prove to be very |
57 |
effective as many questions rise from error messages. |
58 |
|
59 |
Content definition |
60 |
------------------ |
61 |
|
62 |
The topics with the most content would be the issue-type topics who describe a |
63 |
certain error and inform the user about the resolution. To make sure these |
64 |
issues are specific enough (not "how do I fix a build fault") they must |
65 |
describe the following aspects thoroughly: |
66 |
|
67 |
* The *title* describes the issue well enough for most users to quickly find |
68 |
out if the topic is of interest for them or not. It is also displayed in |
69 |
the search results |
70 |
|
71 |
* The *synopsis* gives more detail about the error, such as the full error |
72 |
message, commands that triggered it or the (mis)behavior of a specific |
73 |
command |
74 |
|
75 |
* The *environment* informs the user when the topic applies. If the users' |
76 |
environment doesn't match this one, the topic isn't valid for him. |
77 |
|
78 |
* In the *analysis* section, the cause of the error is considered in great |
79 |
detail to discover the essential flaw that triggered the error. It serves |
80 |
as an information section for the user to comprehend what went wrong. |
81 |
|
82 |
* To fix the error, the *resolution* section guides the user through the |
83 |
necessary steps to resolve the issue. |
84 |
|
85 |
A second type of queries would be small (but interesting) FAQs. These answers |
86 |
are short and precise, most of the time one or two paragraphs. |
87 |
|
88 |
Although several topics will be Gentoo specific, we will not limit ourselves |
89 |
to this. However, we do not add topics that are specific to non-Gentoo |
90 |
distributions. |
91 |
|
92 |
Feedback system |
93 |
--------------- |
94 |
|
95 |
The knowledge base should allow for user feedback. Feedback such as "Does this |
96 |
answer your question?" is invaluable to improve the search results whereas |
97 |
"Mark this topic as outdated" helps us keep the knowledge base in good shape. |
98 |
|
99 |
We might want to consider allowing user comments too: they can add priceless |
100 |
information to the topic, allowing the maintainer of the topic to update it |
101 |
with more accurate information. |
102 |
|
103 |
Topic maintenance system |
104 |
------------------------ |
105 |
|
106 |
Each topic should be maintained by a knowledgeable developer. The system must |
107 |
allow the developer to watch his topics and update them when needed. Of |
108 |
course, topics related to specific herds should be maintainable by the team |
109 |
responsible for the herd. |
110 |
|
111 |
Although not required, revision history would be great :-) |
112 |
|
113 |
License |
114 |
------- |
115 |
|
116 |
The content of the knowledge base should be public domain. Everything large |
117 |
enough to warrant a different license shouldn't be in the knowledge base |
118 |
anyway. |
119 |
|
120 |
Frameworks |
121 |
========== |
122 |
|
123 |
Based on the requirements, one or more frameworks will be chosen. These should |
124 |
of course be free software projects; if we can't find any set of frameworks |
125 |
that adheres to the requirements, the knowledge base project should build one |
126 |
up until the requirements are met. |
127 |
|
128 |
We currently do not have any technical requirements on the frameworks, but at |
129 |
the end the knowledge base should be hosted on official Gentoo hardware and |
130 |
maintained by the Infrastructure project. As such, the Infrastructure project |
131 |
has final saying on the frameworks used in the knowledge base. |
132 |
|
133 |
Copyright |
134 |
========= |
135 |
|
136 |
This document has been placed in the public domain. |