Re: Documentation development processes.

[<jfleck inkstain net>]

On 23 Jan 2001, Gregory Leblanc wrote:
> Dan wrote:
> > 
> > We also need to decide exactly when we want to start implementing this
> > system.  The first test release of GNOME 1.4 is scheduled for 3 weeks from
> > now, with more test releases over the following 6 weeks.  Should we try
> > implementing the review process soon, or wait until GNOME 1.4 is
> > finished?
> 
> Three weeks, eh?  Sounds like I have some serious docs work to check
> on/commit here real quick.  I'd like to see us develop this process as
> rapidly as possible, perhaps having a "final draft" of the process done
> by the end of the week. 

> Clearly the style guide people won't be able to
> finish that on such a short deadline (unless they have WAY more time
> than I think they do). 

You are correct. No style guide that fast, in part because once we get
something, it'll need some serious public vetting on this list.

> I'm not confident that we could apply this to
> the documentation collection before 1.4 ships, although I think we need
> to have the process in place immediately post-1.4, so that anything that
> we re-write for GNOME 2 will show the benefits of this process.
> 

We clearly need two processes: a near-term one for 1.4 (I didn't realize
it would that soon be upon us, though I realize that "three weeks" in Free
Software Time may be different that normal calendrical time) and a more
measured, style-guide-and-editors one for 2.0. The processes we've been
talking about really involve a made-from-scratch doc, and while it would
be nice to apply them retrospectively to all our docs, that's not gonna
happen for 1.4. Not enough time.

> 
> Well, if you want to wait until the doctable is done, that's a
> possibility.  However, only gnome-core has had all of its docs updated
> for nautilus at this point, so there's a lot left to update.  Presuming
> that we've got the process decided upon by next week, I'd say the
> doctable would have the potential to reflect that as early as the first
> test release of GNOME 1.4. 

Having a Working DocTable for 1.4 release would be a *big* help.

Cheers,
John

P.S. gnome-utils docs also are updated and have been tested in the
fires of Nautilus. The makefiles also are fixed to install
the sgml, though the package itself is foobar right now and I have no idea
if it'll be part of a 1.4 release.