Re: An introduction

[Shaun McCance <shaunm gnome org>]

On Tue, 2004-01-20 at 05:06, Patrick Costello wrote:
> Shaun McCance wrote:
> > 
> > > Basically, I just wanted to announce my presence and let everyone know
> > > I'd like to help. I'd be happy to hear from people suggesting first
> > > steps and things I might be able to start out with.
> > 
> > Hi Drew,
> > 
> > Welcome aboard.  I'm not fully awake yet, so what follows is a random
> > listing of largely incoherant tips on getting involved.
> > 
> > We're in feature freeze for GNOME 2.6, which is the most critical time
> > for documentation.  This is when everybody runs around trying to update
> > the documentation for new features, interface changes, etc.  There's a
> > listing of all the documentation in the GNOME Desktop at
> > 
> > http://www.gnome.org/~shaunm/doctable/
> 
> Well, the doctable that I and the rest of the Sun team have been using, and
> keeping updated is at the following location: 
> 
> http://developer.gnome.org/projects/gdp/doctable--.html
> 
> I hadn't realised that we had moved over to a new doctable format. Does
> this mean that we stop updating the doctable--.html file? I did send out a
> few emails not too long ago saying that I had updated the  doctable--.html
> file with jobs that the Sun team is doing for the 2.6 release. As nobody
> said anything to the contrary, I assumed that doctable--.html was still
> active. Although awkward to maintain, the doctable--.html format shows you
> the author at a glance and gives you a good idea that a work is in
> progress. 

The issue is that people want a doctable that doesn't require so much
manual intervention.  The translation team, for instance, has a pretty
awesome translation statistics page that gets build automatically from
CVS.  I would like to have something that pulls all its information from
files that are kept with the documentation and metadata itself in CVS.

This means editorial progress would have to be tracked in CVS, which is
where it should be anyway.  Really, there is way too much information
that's just in somebody's head at this point.  Information needs to be
tracked and accounted for in CVS.  It's the only way that collaborative
development can work well.

> > I'd like people to help review the documentation.  We don't really have
> > any coordinated review process this time around (though I hope to get
> > something in place for 2.8).  Just pick a document and read it.  File
> > bugs about any problems you see.
> 
> The Sun team does have a coordinated review process. We follow the
> guidelines provided in the GNOME Documentation Style Guide (GDSG). Every
> book that we put back to CVS for the GNOME 2.6 Desktop will go through the
> following review cycles: 
> 
> - Technical review, usually done by the developer of the application
> - Peer review, done by another writer
> - Editorial review, done by an editor nominated by the writer
> - Publications review, usually done by the editor
> 
> Within the Sun team we all have sufficient years, indeed decades, of
> experience within the technical documentation industry to work as both
> writers and editors, so we usually do each other the favor of editorial
> reviews. We regularly request peer reviews and technical reviews from other
> community contributors. Therefore, all manuals put back by the Sun team are
> thoroughly reviewed for technical and style requirements. This should
> substantially reduce the burden of reviewing for manuals put back by other
> contributors. 
> 
> Before you [Drew] pick a manual for review, I'd advise you to look at the
> doctable--.html file which gives you an idea if a job is in progress. For
> example, there are quite a few jobs that the Sun team are working on, and
> will complete for the 2.6 release, but we have not put back yet into CVS.
> If you just pick any file from the doctable at
> http://www.gnome.org/~shaunm/doctable/ then you might pick a job that is
> currently almost finished, but not yet put back. In any case, I'd recommend
> you to consult with the designated writer before starting a review, just to
> find out the current status of a job. 

This is starting to be a very serious problem.  While I know that Sun
employs some very good technical writers who produce nice documentation,
we as a community cannot just rely on Sun to do everything on its own. 
Right now, there have been no updates to the User Guide for 2.6 in CVS. 
While you probably have work in-house, nobody else can see this work.

This isn't how anything else works in GNOME, and I don't see any reason
that documentation should be an exception.  Let's say I kept all of my
Yelp work to myself, let a few select friends review it, and then just
committed my work in time to make a 2.6 release.  If I did that, the
release team would be all over me.

The GNOME project relies heavily on its community to review software. 
The only way we can succeed as a free software project is by having a
large and *open* community.  If all your work is in CVS, then we don't
have to worry about whether you have some secret work going on.  Just as
with software, we can always review whatever's completed.  If multiple
people review the same document, it's not "wasted effort".  More eyes
find more bugs.

If we don't have development releases, people can't develop against the
documentation.  For instance, developers aren't going to change where
Help buttons point unless there's a release of the User Guide with which
the new locations will actually work.  But after the Beta 2 release, we
are in a hard code freeze.  So if the User Guide has no releases before
then, it is absolutely impossible to cut out the by-chapter thing.

If the work isn't in CVS, not only can the community not review it, but
our translation team can't translate it.  The translation status page
lists 78 languages that we have people working on.  Is Sun going to hire
a representative of all 78 language teams so that we can have translated
documentation?  I fully intend to implement a documentation freeze for
GNOME 2.8 so that translators can actually translate documentation.

We need work to be open to the community.  It is essential to the way
the GNOME community works.  Updates need to be committed to CVS as soon
as possible, and development releases need to be made according to the
same release schedule that the rest of GNOME follows.

--
Shaun