[Xapian-discuss] Xapian documentation

[James Aylett]

Richard and I were talking over the weekend, and agreed that it's a
good idea for both of us to try to write some more documentation, and
in particular to pull together the various bits of documentation into
a single manual that is both distributable in the tarball and included
on the website. Currently we have various documents that aren't
ordered (or, for that matter, obviously labelled by audience), and the
API docs which don't link back to the rest of the docs; and neither
uses the nice website layout with the RHS menu and everything.

My overall feeling is that the website should be almost entirely links
into the manual. However that's a little in the future.

For now, what I'd like to do is start writing a cookbook-style
introduction to various bits of Xapian; this would include Jim's omega
getting started guide, but also various other things (something
similar for scriptindex, and so on). Much of this content is already
written, but I feel could be presented better for people who don't
already know Xapian. At the same time I'd like to revamp the front
page so it has more of a "If you're trying to do XXX, look at YYY"
feel.

The big question in my head is what to do this book-like manual
in. There are various packages for doing this; we could use something
that likes WikiText (since that has advantages in terms of lots of
people contributing improvements); alternatively we could use Halibut
[1] on the basis that it does indexes really well, and was after all
designed for this kind of use in the first place. I'm sure there are
other viable possibilities.

Thoughts welcome (including "we don't need this because...").

[1] <http://www.chiark.greenend.org.uk/~sgtatham/halibut/>

J

-- 
/--------------------------------------------------------------------------\
  James Aylett                                                  xapian.org
  james at tartarus.org                               uncertaintydivision.org