[Xapian-discuss] Xapian documentation

[James Aylett]

On Mon, May 08, 2006 at 05:43:53PM +0100, Olly Betts wrote:

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

Yes, the internal/non-internal split is done well (although it's not
entirely clear on the index page - or rather, you have to read all the
words, where I'd like big section headers :-), but I suspect we want
to split the "how does Xapian think" up a little so people who don't
want to program to Xapian can read it.

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

Agreed - but actually that's a small part of what I see as the total
content (once I've finished :-).  

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

Home, Features, History, Docs, Current Users (possibly) all make sense
to me. (With my view of the home page.)

Mailing lists, bleeding edge and contact us all contain information
which could be expressed usefully in a manual, but I agree warrant
their own pages on the website for the online-only stuff.
 
> > 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.

I agree we need a FAQ, but this isn't really what I mean here. I see
something like:

======================================================================
Welcome to Xapian!

Xapian is a Foo.

----------------------------------------------------------------------
IF YOU manage a web site and are looking for a packaged search engine,
you want Omega, a richly-featured application built by the Xapian
project. It contains everything you need to get up and running in half
an hour: just follow _the Omega getting-started guide_.
----------------------------------------------------------------------
IF YOU are an application developer who wants to add indexing and
searching to your software, you want to write directly using the
Xapian API. You can either use C++, or one of the languages for which
we supply bindings (currently: big list here); either way, you should
read _overview of the Xapian API_, and then the _API documentation_
for your preferred language.
----------------------------------------------------------------------
IF YOU want to contribute to Xapian's development, you don't have to
get your hands dirty with the library code itself. There are _plenty
of things you can do_, including reporting bugs and improving the
documentation. If you do want to get involved at the code level, you
should first read our _guide to Xapian's code structure_.
----------------------------------------------------------------------

======================================================================

with each _link_ going to a section of the manual. The big advantage
of this is that you can download *everything* you should know about
Xapian in one place. I'm beginning to see this as a /sine qua non/ of
successfuly free software projects; if I can't download it and read it
on my laptop on the train, I'm probably not going to use it in
skunkworks. (So Apache Struts: no hope, JBoss Hibernate: already there.)

The FAQ can obviously link into the manual as well; better, the FAQ
could be part of the manual (this is what we should have done with
Zap) so it's distributed in the tarball.

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

I'd rather use wiki-text, but then we need a way to convert that into
a nice book. If we can do that, let's go for it - if I do a pass over
our existing HTML docs it won't be difficult to wiki-ise them. However
we'd need to know how to do indexing before commiting to that - I
abhore the idea of writing even a small bookworth of information but
not being able to produce a decent index.

Also a wiki doesn't give good disconnected editing operations, whereas
a flat file approach does. We need to solve this - are there any
disconnected wikis? I guess we want a wiki that runs on top of
subversion, then we can just use svk.

Wiki to DocBook thoughts from Hula:
<http://www.hula-project.org/Wiki_Conversion>. Doesn't look terribly
promising, but there may be some stuff that has moved on since then
:-/

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

Aww, halibut is easy. Although acronymic, which is a learning curve
thing :-/

J

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