| 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.
|
Parent Directory
| 
Revision Log