On Tue, Aug 16, 2005 at 01:20:29AM -0500, Jim C. Nasby wrote:
> My experience is that long FAQ's are fine, so long as they're easy to
> search through. This means you've got to support users who may not know
> the magic word to search on. A good example is finding the limits for
> how many rows in a table; searching on limit gets you nothing.
But searching for limit works depending on you search engine, since the
word "limits" appears once. Maybe it's planning or just luck but the
Exim FAQ [1] has always had the question exactly the way I phrased it,
which means even though it has hundreds of questions, it works.
I think the trick is to:
- Include relevent keywords: error messages, config options, command names
- State the question multiple ways if there's no obvious best
> The alternative is to make it very easy for users to skim through the
> TOC to find what they need. Right now that's not very easy to do because
> 2 of the catagories are over 9 items long (humans deal with info best in
> chunks of 5-9 items; most people do best with 7 items or less).
I imagine that perhaps what is needed is a database that has (at least)
a reference to every single possible error message and what it means. I
guess you could call it a "knowledgebase" and there'd be no reason to
keep it small.
I was thinking of more categories, but whatever you do it would make
the FAQ a lot bigger which appears not to be the goal. Although I admit
to reading large chunks of the Exim FAQ because it is full of examples,
just to get a feel of what's possible.
Anyway, I dropped my patch, it's still in the archive and hopefully
this thread has created a enough links to make google take notice. Some
questions now have this patch in the search result so perhaps things
are working as intended.
[1] http://www.exim.org/exim-html-4.30/doc/html/FAQ.html
Have a nice day,
--
Martijn van Oosterhout <kleptog@svana.org> http://svana.org/kleptog/
> Patent. n. Genius is 5% inspiration and 95% perspiration. A patent is a
> tool for doing 5% of the work and then sitting around waiting for someone
> else to do the other 95% so you can sue them.
