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

[Shaun McCance <shaunm gnome org>]

On Fri, 2006-04-14 at 15:30 -0400, Luis Villa wrote:
> On 4/12/06, Brent Smith <gnome nextreality net> wrote:
> > Scott J. Harmon wrote:
> > >
> > > Too bad that documentation is horribly out of date.
> > >
> >
> > Seems like nobody wants to contribute to documentation these days...
> >
> > Updated PDFs for 2.14 at http://www.gnome.org/~bmsmith/gnome-2-14-pdfs/
> >
> > Check out system-admin-guide.pdf for information on how to edit menus.
> >
> > we should really get these on the main site
> 
> Where is library.gnome.org going these days? Completely stalled?

As far as I know, nobody is working on it.  Here's
what needs to be done:

1) Create a customization layer for gnome-doc-utils
to produce the output we want for the library.  Do
try to fold as much code as makes sense back into
the main stylesheets, adding hooks if necessary.

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.

2a) (Optional) Talk to Brent about PDF and get a
solid PDF toolchain into gnome-doc-utils.  Use
this to create PDF versions of all documents.

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.

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

5) Stop and think hard about user interaction.
We want all stable branches of documentation on
the web, but that doesn't mean we want to throw
that all in the user's face all the time.  There
are good ways and bad ways to organize all this
information.

5a) Get a good web design that feels like it's
really part of the Gnome web.  Our designs are
all over the place right now.  Somebody needs
to fix this.  I was trying to put together a
design and some mockups, but I've been working
on a different project lately.

Oh well, I guess I don't need to wait until
it's all polished:

http://www.gnome.org/~shaunm/global/

6) Get people to write good documentation.  We
don't need a massive library full of crap.

People should feel free to talk to me about any
of those steps, but don't count on me doing any
of them.  My plate is too full.

--
Shaun