Re: Documentation development processes.

[Gregory Leblanc <gleblanc cu-portland edu>]

On 23 Jan 2001 12:49:13 -0800, Dan Mueth wrote:
> 
> On Tue, 23 Jan 2001, Alexander Kirillov wrote:
> 
> > May I offer my 2 cents worth of comments?
> > 
> > The process Pat described is very good and thorough, but let's face
> > it: at the moment we do not have anywhere near the manpower
> > needed. So, IMHO, it is more important to start some kind of
> > editing/review/... framework as soon as possible; better have
> > something simple working now than a detailed (but unrealistic) plan in
> > 4 months. After we get this started, we can add more steps to the
> > process. Yes, I undersatnd that this is a trade-off in quality - I am
> > ready to accept this. 
> > 
> > For now I think the top priorities should be finding editors and
> > indexers for each document. Can we do that? Do we have enough
> > volunteers? 
> 
> I think we can certainly try.  My previous experience with recruiting was
> fairly positive, and I expect we can get a few experienced indexers and a
> few experienced editors without too much trouble.  With a little more
> effort, we may be able to assemble larger teams.

I've also had good luck recruiting people, given specific tasks,
especially ones that are "unencumbered" by things like checking on
copyrights and such.  If we say we're looking for Indexers and editors
to attack a set of documents, I think we'll be able to find them easily.
Having a good style guide and such will also make it easier for people
to hop on board.

> I think the key here is to first develop a very good framework for our
> process and development. This includes finishing this discussion and
> writing it up nicely, as well as thinking through how people will interact
> with each other, with CVS, with the DocTable, etc.  If we have a
> well-thought-out and documented system set up, I think it will make it
> much easier to attract and keep professional indexers and editors.
> 
> 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).  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.

> Also, should we wait until the DocTable is updated to reflect the new
> system?  Gregory - How long do you think it will take to do the redesign?

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.  I'll mail a design doc on the doctable
site/database in a few days, once I've finished thinking it out.  The
re-design of the pages is close to done, I just need to figure out the
implementation details, and the database.  Clear as mud, right?  Later,

    Greg