/[gentoo]/xml/htdocs/proj/en/glep/glep-0051.txt
Gentoo

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.1 - (hide annotations) (download)
Wed Aug 16 19:25:14 2006 UTC (8 years, 2 months ago) by liquidx
Branch: MAIN
File MIME type: text/plain
adding glep 51 - kbase from swift

1 liquidx 1.1 GLEP: 51
2     Title: Gentoo Knowledge Base
3     Version: $Revision: 0.0003 $
4     Last-Modified: $Date: 2006/06/15 19:32:36 $
5     Author: Sven Vermeulen <swift@gentoo.org>,
6     Status: Draft
7     Type: Standards Track
8     Content-Type: text/x-rst
9     Created: 30-May-2006
10     Post-History: 16-Aug-2006
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.

  ViewVC Help
Powered by ViewVC 1.1.20