Re: [gentoo-kbase] A Gentoo Knowledge Base

[Mike Myers]

Hi

I really like your idea so far.  I'm glad you plan on making this part
of the official gentoo project as well, as I'm almost positive something
like this would have popped up eventually that was unofficial.  Anyways,
something you may want to consider in searching is the ability to search
for specific error messages.  Speaking from experience, often times when
I am searching for a problem, it's how to fix an error message and I'll
use the error message itself as the search criteria.  The natural
language thing seems like it would be decent, but it almost seems like
it would require a bit of artificial intelligence, which might be more
work than what it is worth.  It would be great though if it did turn up
useful results.

Another function you should be sure to put in is the ability to browse
by category or something.  Some people tend to end up with problems that
they never get fixed and just forget about them.  (I know I have)  Or if
they're just curious about how a particular program might be set up.  I
hope you get the idea of what I'm saying.

Overall though, I think your ideas are great.  Like the PHP.net style
comments and whatnot.  Gentoo has been known for it's documentation for
a while, but that reputation seems to have diminished a bit since there
hasn't been any huge changes in how things are done.  I really think a
KB like this would remedy that.

Mike


Sven Vermeulen wrote:
> 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-kbase@g.o mailing list