en/glep/glep-0051.txt

GLEP: 51
Title: Gentoo Knowledge Base
Version: $Revision: 1.1 $
Last-Modified: $Date: 2006/08/16 19:25:14 $
Author: Sven Vermeulen <swift@gentoo.org>,
Status: Withdrawn
Type: Standards Track
Content-Type: text/x-rst
Created: 30-May-2006
Post-History: 26-Mar-2007


Abstract
========

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.


Motivation
==========

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.

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.

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. 


Requirements
=============

Search functionality
--------------------

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.

Content definition
------------------

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 "how do I fix a build fault") they must
describe the following aspects thoroughly:

*  The *title* 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

*  The *synopsis* gives more detail about the error, such as the full error
   message, commands that triggered it or the (mis)behavior of a specific
   command

*  The *environment* informs the user when the topic applies. If the users'
   environment doesn't match this one, the topic isn't valid for him.

*  In the *analysis* 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.

*  To fix the error, the *resolution* section guides the user through the
   necessary steps to resolve the issue.

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.

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.

Feedback system
---------------

The knowledge base should allow for user feedback. Feedback such as "Does this
answer your question?" is invaluable to improve the search results whereas
"Mark this topic as outdated" helps us keep the knowledge base in good shape.

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.

Topic maintenance system
------------------------

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.

Although not required, revision history would be great :-)

License
-------

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.

Frameworks
==========

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.

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.

Copyright
=========

This document has been placed in the public domain.
1	liquidx	1.1	GLEP: 51
2			Title: Gentoo Knowledge Base
3	nightmorph	1.2	Version: $Revision: 1.1 $
4			Last-Modified: $Date: 2006/08/16 19:25:14 $
5	liquidx	1.1	Author: Sven Vermeulen <swift@gentoo.org>,
6	nightmorph	1.2	Status: Withdrawn
7	liquidx	1.1	Type: Standards Track
8			Content-Type: text/x-rst
9			Created: 30-May-2006
10	nightmorph	1.2	Post-History: 26-Mar-2007
11	liquidx	1.1
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.