Get Gentoo!

GLEP 51: Gentoo Knowledge Base

Author Sven Vermeulen <swift@gentoo.org>
Type Standards Track
Status Withdrawn
Version 1
Created 2006-05-30
Last modified 2014-01-23
Posting history 2007-03-26
GLEP source glep-0051.rst

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.