Re: An introduction

[deirdre williams <Deirdre Williams Sun COM>]

Hi Shaun,

I am a Program Manager working in Sun and I have been working closely with the tech pubs team in Sun for about a year now. I've been on the gnome-doc-list alias for a while, but I haven't contributed as I'm not a tech writer and generally haven't had much to say, until now

You seem to think that there is work going on in Sun that you don't know about. Why are you worried about "secret work going on" in Sun? The Sun documentation team have always been very upfront about the projects they are working on, the existing doctable says it all. How many other contributors routinely announce what they plan to do in advance on the gnome-doc-list, then include the information in the doctable, then announce that they have done putbacks? 

You are correct when you say "we can always review whatever's completed". ALL the
documentation that has been completed by Sun has been putback to the community in a timely manner. There is no point in making a half-completed document available for review.

Bear in mind that the Sun GNOME release is always behind the community but even so the tech pubs team have always managed to fullfil their commitment to the community by keeping their documentation up to date for the community releases.

Dee

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

-- 

Deirdre (Dee) Williams
Program Manager
Desktop Solutions
Tel: +353 1 8199133
Extension: 19133