/[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.2 - (show annotations) (download)
Mon Mar 26 10:27:50 2007 UTC (7 years, 9 months ago) by nightmorph
Branch: MAIN
CVS Tags: HEAD
Changes since 1.1: +4 -4 lines
File MIME type: text/plain
Marked glib 51 (kbase) withdrawn

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.

  ViewVC Help
Powered by ViewVC 1.1.20