From kde-usability  Tue Aug 31 19:08:41 2004
From: Aaron Seigo <aseigo () kde ! org>
Date: Tue, 31 Aug 2004 19:08:41 +0000
To: kde-usability
Subject: Re: Single vs Multi Window KControl
Message-Id: <200408311308.41322.aseigo () kde ! org>
X-MARC-Message: https://marc.info/?l=kde-usability&m=109397939911073

On August 31, 2004 11:49, Charles de Miramon wrote:
> Le mardi 31 Août 2004 03:00, Aaron Seigo a écrit :
> >  o we will be using full text indexing, not keyword searching
>
>  I agree that full text indexing has advantages over a keyword system but I
> see also problems.

s/problems/challenges to overcome/g 

;-)

>  - How do we cope with KCM (or group of options) where they are no help
> written (yet). With a full text indexing search, the options won't appear.

we make it policy that anything that appears in KControl must:

 1. have a corresponding KConfigXT xml file
 2. have documentation for every option
 3. have some general documentation for the group

> You must understand that the documentation is lagging behind development.

actually, kcontrol documentation is pretty good. have you browsed through in 
3.3?

> Another problem is that some pieces of our documentation are very verbose,
> some are nothing more than a sketch and the inegal quality (or length) of
> documentation can fool a full index search algorithm.

this is at least partially true. the challenge here is that we don't value 
documentation enough, especially when it comes to kcontrol. but this is 
completely fixable, especially if this fixes larger problems we have.

just because the solution takes work doesn't mean that sticking with the 
current problems is a better proposition =)

>  - How do you sort the result. A quick count in the documentation reveals
> that we have for example 1219 hits for the word 'mouse' in the
> documentation and that the document with the most occurences of the word
> 'mouse' is the kmousetool documentation. Sorting the result by number of
> occurences would put on top a link to an accessibility tool needed by a
> minority not to the most relevant KCM for mouse configuration.

it won't search all the documentation, just the KCMs. why would it search 
through application docs? that makes so little sense it isn't even funny, and 
if you think that's what i was suggesting let me assure you i'm slightly more 
clever than that ;-)

the big question will be, as you hinted at a bit, heuristics. i would suggest 
we look into doing some or all of the following:

 o weighting the "general documentation" (e.g. "This kcm does...") higher than 
the per-widget documentationsomething like
 o combining ALL occurrences of hits in each kcm when weighting, which will 
tend to weight it better towards overall content/context
 o take into consideration mark-up in the documentation, so that headings and 
highlighted sections are weighted higher
 o use proper FTI which means taking into consideration phrasing. note that 
virtually all SQL engines currently come with quite effective FTI 
imlpementations.

> IMHO, keywords have the following advantages :
> - if the number of keywords is not too big, you can give an interface where
> people can browse through them (like in the actual KControl)

if the number of keywords is small, it's useless. try it out and see =)

on the other hand, we are once again back to hierarchical via a slightly 
different mechanism. and, once again, hierarchical *does not work* in this 
application.

> - like I've said in a previous e-mail, we could pair a keyword with a
> relevance value to sort the result in a meaningful way (the most relevant
> at the top)

a question of heuristics, yes... it may be interesting to be able to lace the 
documentation with explicit "emphasis" marks...

> - we could add keywords to options or group of options, when the
> documentation is today application centered or KCM centered and full text
> indexing search will come back with links to applications not options.

then you are approaching exactly what we're suggesting, but instead of 
re-using the words already there you are suggesting we duplicate the 
documentation effort. this is folly.

> The best of two worlds would be in my opinion to combine a keyword system
> and a full text index of the documentation and if a keyword search does not
> work give the result of the full text search.

except that the keyword system is not entirely useful in this regard as it 
relies on people come up with accurate keywords and maintain them. neither of 
those things happens on a consistent basis, whereas documentation is kept up 
quite nicely.

-- 
Aaron J. Seigo
Society is Geometric
_______________________________________________
kde-usability mailing list
kde-usability@kde.org
https://mail.kde.org/mailman/listinfo/kde-usability