Re: An introduction

[Patrick Costello <Patrick Costello Sun COM>]

Your reply was very thought provoking. I need to discuss the implications
of these statements with the rest of my colleagues in the Sun team. I will
get back to you. 

Pat

Shaun McCance wrote:
> 
> 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
> 
> _______________________________________________
> gnome-doc-list mailing list
> gnome-doc-list gnome org
> http://mail.gnome.org/mailman/listinfo/gnome-doc-list

-- 
**********************************************
Patrick Costello, GNOME Documentation
Phone: 		01 819 9077 [ext 19077]
**********************************************