Rename all GLEPs to .rst

1 files changed, 138 insertions, 0 deletions

diff --git a/glep-0051.rst b/glep-0051.rst
new file mode 100644
index 0000000..d6f1af0
--- /dev/null
+++ b/glep-0051.rst
@@ -0,0 +1,138 @@
+GLEP: 51
+Title: Gentoo Knowledge Base
+Version: $Revision$
+Last-Modified: $Date$
+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 deepened to an almost
+individual, precise answer for every question. It is no longer reasonable to
+suggest that documentation is sufficient to successfully aid 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 work is licensed under the Creative Commons Attribution-ShareAlike 3.0
+Unported License.  To view a copy of this license, visit
+http://creativecommons.org/licenses/by-sa/3.0/.