[Xapian-discuss] Writing a Quick Start Guide to Xapian

[Olly Betts]

On Tue, Oct 11, 2011 at 09:04:41AM +0200, Websuche :: Felix Antonius
Wilhelm Ostmann wrote:
> I followed this subject, but currently i am not total sure what will
> happen there ...
> 
> we want to write a ?small? book with the titel "a Quick Start Guido to
> Xapian"?

Yes - the title isn't fixed as that necessarily, but that sums up what
it should cover pretty well.  People seemed to think a "cookbook" style
with examples of how to do various common tasks would be good.

> Or only something for the xapian.org homepage?

We'd ultimately want it available in a form such that it can be easily
read online, and licensed under a licence that grants the freedoms that
the software itself has.  So I wouldn't fixate on the "book" part too
much.  The economics of traditional book publishing aren't good for
most authors, so producing a printed version isn't really the goal, but
it would be good to have a version suitable for printing or viewing as
an e-book, etc.

> How small will this guide be? For which native languages? For which
> programming languages?

I took part in a 2-day sprint to write a guide for mentors in GSoC, and
with 8 people we produced an 80 page manual.  I doubt you can directly
convert, and I'm not sure how many people we'll have, but I'd hope for a
slim but non-trivial book.

The initial version would be in English, but if people want to work on
translations that would be great.  You probably want to wait until after
the sprints though, to avoid chasing a changing target.

I'd like to have versions of the book for each supported programming
language, with an easy way for people to supply equivalent example code
for other programming languages.  To make best use of the limited sprint
time, I think we should just put one version of each example in to start
with.

> Can someone helping by rereading the output from other places? What do
> you exactly expect from helping hands? My english is not best, so how
> can i help?

Splitting the sprint over two weekends seemed like it would work for
more people, but isn't so helpful if you are outside SE England - if
you're able to make it that's cool, but if some people want to join in
remotely, that can work.  As you suggest, reading through and improving
text doesn't require strong interactions.

The plan for those attending is we'll come up with a approximate outline
for chapters and sections, and then people will start to fill those in.
As we go, we can adapt the structure, and read over and improve the
text.  If there's useful existing text (e.g. the current documentation,
or blog posts people have written) we can potentially incorporate that
if the licences allow it.

Cheers,
    Olly