Our Discussion on Fedora-docs [Fwd: Re: Fedora Documentation Search Engine]

[Karsten Wade]

On Sat, 2005-01-29 at 06:35 -0500, Bryan Clark wrote:
> Hi ~
> 
> I'm not questioning the benefit of the inclusion of swish into extras,
> but I'm wondering what the end-user benefits are going to be of adding
> an indexer for the documentation.
> 
> >From reading the small thread on fedora-docs I understand that you would
> like people will be able to search all the man-pages/howto/README docs
> of the installed rpms.  What I'm looking for is some more basic details
> of why this needs to be done and why it needs to be done this way.
> 
> What type of person do you think is looking for this information (a
> developer, an office worker, a broker?).

Any end-user on the system.

> What is this person trying to accomplish by searching this information?
> Why do they need it?

Currently, the best way to search for Fedora documentation is via
google.com.  That in fact is how I search Red Hat docs, using
site:redhat.com.

Right now, if you install locally all the documentation available, you
might have everything you'd be searching Google for but are unable to
find locally.  Package docs go into /usr/share/doc and the man pages,
Red Hat docs packages also go into /usr/share/doc and may have an entry
in the 'Foot/'Hat menu.  Fedora docs are small enough that an Everything
install _could_ include docs packages.  That is a *tonne* of local,
online documentation.

All of this is nearly impossible to search through without an index and
search tool.

> Assuming they need it.  How are they going to search for this
> information?  Yelp?  Web Browser?  Something else?  Are the mechanisms
> for searching and reviewing this type of information already built into
> those things?

IMO, Yelp.  We need to settle on a common help interface and (ab)use it.

For example, a document on using kickstart to automate installation
might be at the forefront when Yelp is called from system-config-
kickstart.  If an indexer can do this well, it seems better than hand
coding docs to be associated with certain apps and actions.

> If we had more of an overview of how this project is going to help
> people we could possibly look at a way of integrating it's functionality
> better into our system.  Hopefully we then won't be just adding another
> piece to the stack of tools we have, but an answer to a problem people
> are having.

I definitely think integrating indexed documentation into Yelp is a good
idea for corporate-type end-users.  People _used_ to use the local help
system more extensively, until Internet search engines proved more
useful.  The downside of relying upon the Internet is, what do you do
when the doc you need is the one that will get your networking going
again?  Better hope you have a second machine that has connectivity, or
that you know how to dig through /usr/share/doc by hand.

- Karsten
-- 
Karsten Wade, RHCE * Sr. Tech Writer * http://people.redhat.com/kwade/
gpg fingerprint:  2680 DBFD D968 3141 0115    5F1B D992 0E06 AD0E 0C41   
               IT executives rate Red Hat #1 for value              
                 http://www.redhat.com/promo/vendor/