Re: Documentation on the web

[Shaun McCance <shaunm wolfram com>]

On Mon, 2003-08-25 at 11:24, Patrick Costello wrote:
> Hi Sean, 

Shaun  :)

> 
> You are doing some great work in getting GNOME user documentation onto
> the web. Your approach looks very promising, and looks like a great
>  contribution. Some thoughts, suggestions and questions: 
> 
> - I think that this approach is the most useful for the "heavyweight"
>  documentation. The stuff that people like to bookmark and reference
>  from time to time. Or even print out. The GNOME 2.2 Desktop User Guide,
>  the GNOME 2.2 Desktop Accessibility, the GNOME 2.2 System Administration
>  Guide, for example. The fairly long revision cycle for these larger books
>  would suit the library approach. 

Yes, I had every intention of putting these documents in.  That's what
the 'Desktop' category was for.  If you look at the components that are
actually in my build tree, you might notice that I just went through the
2.3.6 packages alphabetically, and basically stopped at gdm.  As I said,
I was just trying to make stuff work.  More documentation needs to be
plugged in, and the categorization should be reworked.

> - I think that trying to provide a comprehensive library of the individual
>  application online Help manuals could prove to be mission impossible.
>  These manuals are constant works-in-progress, always under revision,
>  and therefore always out-of-date if placed in a library. Users are less
>  likely to want to access the application manuals as works of reference. 

Well, software is always under revision as well, but we do manage to
make releases.  The versions of documentation I've built correspond to
milestone releases of the corresponding piece of software.  One of the
advantages of GNOME's release cycle is that documentors should have a
chance to polish documentation for a particular release of software.

I think it's useful to have the application manuals on the web, and to
keep documentation online for all major versions.  These can be used as
reference for people answering question on gnomesupport.org.  We also
would have a definitive location for versions of documentation, so they
could be referenced unambiguously by URLs (which could allow us to get
rid of that silly ghelp URI scheme some day).

Also, with an automated build tool, it's not that hard to keep things
current, even with all the application manuals there.

> - Does your approach offer a resolution to the permanently out-of-date
>  status of project-support documentation, such as the GNOME Documentation
>  Style Guide and the Human Interface Guidelines? There have been updated
>  revs of both the GDSG and the HIG putback to CVS for some time, but the
>  updates have never made it onto the web. It would be really great if your
>  approach broke that logjam. 

Currently, the build system only knows how to grab tarballs of releases.
This was designed around the idea that modules actually make releases,
rather than building off of whatever happens to be in CVS.  However,
more stuff can be plugged into this system, so if it would be useful to
have docs that are built from CVS, then CVS-grabbing tools can be made.

Incidentally, I think the developer documentation should have multiple
versions on the web, much like the application manuals do in my system. 

--
Shaun, whose mother thinks that Sean should be pronounced 'seen', and
whose father thinks that Shawn is a girl's spelling.