[Xapian-discuss] Xapian docs

Andrew Betts andrew.betts at assanka.net
Thu Apr 21 10:17:31 BST 2011


On 20 Apr 2011, at 15:16, Olly Betts wrote:

> On Sat, Apr 02, 2011 at 12:47:21PM +0100, Andrew Betts wrote:
>>> I think this is a shining example of how well Xapian works with large
>>> document collections. I was just discussing this with my colleagues here
>>> and one of the issues that came up is that we'd love Xapian to become
>>> really lot more popular but have found that the documentation's a bit
>>> difficult to get into, as is the API. 
>> 
>> I agree.  There are a few gotchas, as well as branch stuff like
>> matchspy that is phenomenally useful, but largely undocumented and
>> therefore underused.
> 
> I don't think it's reasonable to expect complete user level
> documentation for features under development on a branch.

I don't expect that.  I'm saying there are people (like me) who would be prepared to provide it if we had a well understood and well organised way of doing so, so that people would get value from them.  Personally I find matchspy an incredible bit of kit and it would be nice to be able to share what we've learned in a way that offers the most value to other potential users.

> Hmm, well, we already have higher level documents written by the
> development team and consistently formatted which cover most of the
> newer features - for example, facets are covered here:
> 
> http://xapian.org/docs/facets.html
> 
> These are all linked to in a list on the doc index page:
> 
> http://xapian.org/docs/
> 
> Did you just not find these (in which case we partly have a navigational
> problem)?  Or are you looking for something else?  Or just missing
> these for the older features (which naturally tend to be the more
> fundamental ones which users will want to get to grips with first)?

Example: I can never find the page on PHP bindings.  I always have to find it through Google.  Looking again now I realise there's a link to it right there on the homepage, but not in the documentation index!  I had always gone to docs, and then got stuck.  And the page itself, when you do get there, doesn't link to anything.

My personal feeling is that at the low level Xapian's docs are excellent (really want to stress this), and at the high level they're a bit disorganised and there's not really a sense of a grand strategy binding it all together.

Anyway, I'm just chipping in from the perspective of someone who's used Xapian to solve some complex use cases.  I know I don't have anywhere near enough experience with it to do anything beyond contributing the bits I've learned to a documentary effort, but what I'm saying is that I'd be very happy to do so if I found the right place to do it - whether that's a few code examples in PHP, description of indexing and searching strategies for particular use cases, or guidance notes on classes or specific methods.

Andrew




More information about the Xapian-discuss mailing list