[Xapian-discuss] Xapian documentation

[Olly Betts]

On Mon, May 08, 2006 at 08:56:07AM +0100, James Aylett wrote:
> 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.

That would be good.

> Currently we have various documents that aren't ordered (or, for that
> matter, obviously labelled by audience)
    
That's not totally true - http://xapian.org/docs/ suggests a reading
order to get people started, and also divides the documentation into
at least "internal" and "non-internal".  But there's plenty of scope
for improvement.

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

I don't think it makes sense to try to move parts of the website which
require an internet connection to use into the manual - you'll need to
be connected to use them and by keeping them on the site we can make
sure people aren't seeing an old version (e.g. mailing list information,
bug reporting information, SVN access information, download information).

In fact, looking at the side menu, I can't see much which I think would
make sense in the manual, so I'm not quite sure what you have in mind...

> 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.

We really need an FAQ list, which could house such questions and answers
if they grows beyond what can reasonable go on the front page (which I
think would happen quite quickly!)  It's the natural place to look for
such answers too.

> 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.

As I've said before (but not made much progress towards sadly) I'd like
to be able to house the documentation (or at least a copy of it) on the
wiki to allow users (and indeed developers) to easily correct and extend
it.  

So using wiki-style markup would make a lot of sense (the main obstacle
I found to moving the current documentation to the wiki is the need to
convert the markup - it's easy to do a quick conversion, but I found the
details hard to get right).  Wiki markup also has the benefit that you
don't need to think about it so much.

Otherwise, DocBook (probably in XML rather than SGML) is a reasonable
choice - I've used it before so it's not a whole new markup language
for me to learn (like halibut would be).

Cheers,
    Olly