[gentoo-kbase] A Gentoo Knowledge Base

[Sven Vermeulen]

I suppose this is a good a time as any to tell you a bit about what I had in
mind, or more precisely, why I have it in mind.

On occasion, I go through some topics in the Gentoo Forums, helping where
I can with the installation (as I'm a bit to blame for the installation
instructions). I noticed that many questions come back which shouldn't come
up if someone followed the Gentoo Installation Instructions verbatimly - but
then again, I do realise that many installations want more/less partitions,
use a different filesystem, want LVM/RAID, ... so they are all quite
different from each other.

One of the topics that comes up very often is the "Kernel Panic: Unable to
mount root fs" problem. To solve it, you need either a good guiding hand, or
good documentation. So I started writing a guide on this, but quickly
realised that many more documents would have to be written to solve other
problems.

Enter the idea of a Knowledge Base.

Such a system would contain specific answers to specific questions. The
answers should be easy to understand and follow and should leave no room for
different interpretations. So when someone starts reading the topic, he
should either think "Yes, this is exactly what I'm having" or "No, this is a
bit different from what's happening on my system". 

To make sure topics are well structured, I was thinking about something like
  <title>
  <synopsis>
  <environment>
  <analysis>
  <solution>

The title should be dense but clear: a user searching for a solution often
only sees the title. Hence, he should be able to understand that the topic
is either a good candidate for his problem, or no candidate. 

The synopsis describes what happens, such as error message, or abnormal
behavior, including a specific action that triggered it if the trigger is
clear (not an example trigger, but /the/ trigger).

The environment tells what is configured for the problem to occur. This can
be very simple (or even empty) and is an aide to the user to verify if the
described problem really focuses on his issue. If the environment sais that
the issue occurs with LILO being installed and the user has GRUB, this
should be sufficient for the user to know this doesn't apply to him. The
environment is also a way to tell developers not to write generic topics -
those are documentation guides, not knowledge base topics. 

The analysis informs the user why the problem occurs, and is meant to teach
him about the system. Users not interested in learning might want to skip
this (and come back if they can't figure out the solution without, but this
should be quite infrequent).

The solution is a step-by-step instruction on the solution for the problem.
This can (and probably will be) very dense too, such as "rebuild the kernel
and install it (with a reference to the kernel upgrading guide)" or "edit
grub.conf and change the 'default' setting to blabla". Of course, some
topics will require a large explanation - that's fine too.


Of course, having many topics doesn't help if the user can't find them. This
would require a good search engine. Most good search engines are related to
the technology used, so while searching for a good framework (or starting
the development of one) we should focus on the search engine that's part of
it. 

The best search feature is a natural language expression. A user that can
type in his problem will really appreciate this, and if I may believe most
sites on natural language queries, they are more likely to provide enough
information to find the result that suits the user best.

One more feature that I would like to see in place, but isn't mandatory, is
a user feedback system like PHPs. Although this might (or probably will)
require maintenance and rules (like no trolling, asking for help -> forums,
...), it would make the KB not only a good asset for Gentoo for information
retrieval, it would also give the users a chance to contribute (good
comments might lead to an update of the topic) /and/ be sure that what they
say is noticed (as it is displayed).

I have consulted the infrastructure project a bit about supported
technologies. PHP and MySQL is supported (which brings a lot of frameworks
into play), others (like Java EE) aren't, but that doesn't mean they will
never be. It just means that, if we want a different technology, we'll need
to persuade more, perhaps even have a couple of admins in the infrastructure
project to make sure that the technology is well maintained (in case of
emergency, security issues, ...).

Before I lay down a plan on what to do, I hope to hear from others (that
means you) what you had in mind when hearing about a "Knowledge Base"? Does
it fit with the description on the KBase project site
(http://www.gentoo.org/proj/en/kbase)? 

Wkr,
      Sven Vermeulen

-- 
  Gentoo Foundation Trustee          |  http://foundation.gentoo.org
  Gentoo Council Member  

  The Gentoo Project   <<< http://www.gentoo.org >>>