Re: An introduction

[Patrick Costello <Patrick Costello Sun COM>]

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. 

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

> 
> It helps to be running the development series of GNOME, so you can see
> the new features and know what remains to be documented.  But you can
> also look for spelling and grammar errors, questionable style, problems
> with the DocBook markup, etc.
> 
> Also check out
> 
> http://developer.gnome.org/projects/gdp/resources.html
> 
> You'll see links to the Handbook and the Style Guide, both of which are
> worth reading if you'd like to work on the documentation.
> 

Personally, I would begin with the GDSG if you want to start with reviewing
and editing. You need a benchmark to review against. The GDSG provides that
benchmark. You need to read the GNOME Handbook of Writing Software
Documentation if you want to start implementing written work.

> A lot of us hang out on IRC in the #docs channel on irc.gnome.org.
> 

It must be something to do with the timezone that I am in, Dublin, but
whenever I log onto the #docs channel, there is no-one there. I would like
to participate from time to time, but it's a question of knowing when
anyone is online. Please do not misinterpret my absence from irc as a sign
of lack of interest. 

Pat

_______________________________________________
> 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]
**********************************************