Re: Documentation development processes.

[Gregory Leblanc <gleblanc cu-portland edu>]

On 23 Jan 2001 15:18:14 -0800, jfleck inkstain net wrote:
> 
> 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.

Ah, what's this letting other people look at it?  :)

> > 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.

I'm NOT going to have time to do any editing before 1.4 the way that
things are going.  I'm looking at 12 hours a day the rest of the week
since people are out of town, and then I'll only have two weeks to get
all of the core GNOME packages fixed.  The BIG (114 files, last I
counted) one that's left is gnome-applets, but I think Telsa is going to
do that one for me.  <grin>.  At least Alan wrote some tools to speed
that up.

> > 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.

Does that mean NOT the current one?  I won't be taking the old one down
while I work on the new one, and the new one will probably reside at
d.g.o, rather than www.gnome.org so you should have at least that, for
the time being.

> 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.

I'm not touching makefile, as nobody has showed me what to change.  If
you'd like me to do those updates as well, give me a tutorial some time.
Off to more docs hacking now, ttyl.

    Greg