Re: Overall State of Documentation [was Re: Gnome is a problem for OEMs]

[Jeff Waugh <jdub perkypants org>]

<quote who="Shaun McCance">

> 2) Create a build script that can take a list of all our documents from
> all relevant branches of all relevant modules and produce the HTML.

Better to use tarball releases.

> 3) Set up a system that tracks CVS and rebuilds the live documentation
> whenever needed.  Forget waiting for releases; just track CVS for stable
> branches.

I really disagree with this - simply making regular releases has brought a
solid discipline to our code modules that they wouldn't have otherwise. The
same applies to documentation.

> 4) Get a box set up to run this code and host the library.

A simple 1.0 version, using totally static output, could be hosted without
any worries on existing infrastructure. That isn't a barrier to completion.


I did some simple shell-and-tarball versions of this when I tried to get it
going. All it needs to start with is a little bit of metadata (for instance,
storing the index file for each blob of documentation [1], versions, etc),
and a script that goes through tarballs to produce the output. At that point
we can start building output on every tarball release (separating by maj.min
versions), producing alternative formats (translations, pdf), and pushing
out other data such as trees made from devhelp files, search indexes, etc.

It's really simple, and doesn't need an architecture astronaut to complicate
it! I did maybe 30% of the useful stuff as a simple script, but really don't
have the cycles to do it in a way that is maintainable or long-term useful.

I wouldn't mind writing the first level specs as a SoC project, in fact.

- Jeff

[1] there are a few useful blobs in glib, so you need to be able to produce
    more than one document from a single tarball

-- 
linux.conf.au 2007: Sydney, Australia           http://lca2007.linux.org.au/
 
     "Old timers will tell you what a pain unstable was during the new
        testament transition." - Jon Corbet on Debian's KJV packages