Xapian discuss - May 2006 - Xapian documentation

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@tartarus.org                               uncertaintydivision.org

James Aylett wrote:
 > 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

This kind of document is certainly something that I would have liked to
have had when starting with Xapian. 

Did you consider DocBook SGML as a document format ? 

It has many users and usages and a lot of support behind it.

jf

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