Re: our online docs

[Shaun McCance <shaunm gnome org>]

On Tue, 2006-02-07 at 21:15 +0000, Joachim Noreiko wrote:
> --- Shaun McCance <shaunm gnome org> wrote: 
> > If we used my stylesheets, this stuff would
> > automatically
> > be put onto a separate title page. 
> 
> Can we?

Absolutely.  If any issues come up, then we just
need to tell me, and I can get them fixed.

> > But what's on the web now is outdated 
> 
> yes.
> 
> > and built manually.
> 
> eek!

Yup.  We need to contact the web folks to see
how to put newer builds up.

> > So who wants to build library.gnome.org?
> 
> This isn't the first time you've mentioned this.
> What's the general idea for it?

In theory, we have a whole bunch of documentation,
pretty much all of it in DocBook.  We have desktop
docs (User/Accessibility/Admin Guides), all of the
application manuals, the developer references, a few
developer tutorials, and the guides produced for the
subprojects (GDP, L10N, HIG).

We want a single site, library.gnome.org, where all
of the documentation is built automatically and kept
in perpetuity.  We want, for example, to be able to
access the 2.10 Sound Juicer Manual at something like

http://library.gnome.org/apps/sound-juicer/2.10/

We don't care so much about point releases.  The 2.10
build, for example, would just be taken from the most
recent 2.10.x release, or possibly from the latest in
CVS on the gnome-2-10 branch.

We want frequent builds of the unstable documentation
we're preparing for the next major release as well.
But we want the site navigation to try to lead you to
the latest stable stuff.

I generally try to avoid bringing my employer into
these threads, to make it clear that my involvement
with Gnome is entirely my own.  But I can't think of
a better example of this done so well:

http://documents.wolfram.com/

<ego>The people behind that are quite possibly the
greatest documentation programmers ever. ;-)</ego>

We need the infrastructure to put this all together.
We have more of it now than we used to, now that we
have my stylesheets and build utilities.  But it takes
more than that.  Also, we need a hefty machine that
can actually chug this stuff out every night, since
building the documentation often involves building
the entire module.

--
Shaun