Re: Workflow questions

[Shaun McCance <shaunm gnome org>]

On Fri, 2009-03-27 at 16:35 -0500, Paul Cutler wrote:
> Hi, as I tackle some of the outstanding GNOME docs using Pulse, I had
> a couple questions as it relates to workflow.
> 
> I've been using LGO, Shaun's email from January
> (http://mail.gnome.org/archives/gnome-doc-list/2009-January/msg00028.html)
> and the Status Tracking on LGO as guides, but I need some
> clarifications, especially around the review process / status.
> 
> As I wrap up working on a document, I submit a patch on Bugzilla with
> the updated docs and let the developers know in IRC or on the
> project's mailing list.  If I think it's done, I'll put the status as
> "techreview", and hope the project developers have time to review and
> commit.  Should I be asking on the docs mailing list for a peer review
> first, especially as the LGO Status Tracking page recommends 3 peer
> reviews?
> 
> Once the doc is in tech review status, when should I be moving the
> document into "candidate" status or "finalreview"?  (And what is the
> difference between the two?)  Should it be after the project developer
> reviews and commits?  (What if they're busy and weeks or months go
> by?)

Sorry if this isn't clear: "techreview" and "finalreview" aren't
statuses.  They're types of reviews.  You should use the status
"review", then add ulink elements for each actual review you get.
See the example at the very bottom of the page.

As for how to get the reviews and how many to get: Three peer
reviews is a goal, not a requirement.  For smaller documents,
it's less important.  But you'd be surprised what a fresh pair
of eyes can find.  Peer reviews don't even have to be done by
writers.  Find a developer or enthusiastic user.  But do try
to get at least one from somebody you trust to proofread well.

Developers are, of course, busy people.  And since many of us
are volunteers, we have to be prepared for the possibility that
some developers won't be available every day.  Do try to budget
around a week for developers to get back to you.  If you're not
getting any response from them, ping gnome-doc-list.  I may be
able to find another developer who's knowledgeable enough for
the document in question.  Or I'll pester people myself.

> I'm curious about the candidate status as I hope to use Pulse to move
> through some documentation over the next couple of weeks.  My process
> is to usually review Bugzilla for any requested doc updates, go
> through the document and compare it to the app's behavior, and then
> update the document to add Pulse status and any bug fixes and then
> submit a patch.  I have a feeling that some of the docs out there
> won't need a lot of changes, so I can move through them and get the
> patches out there, but I'm not sure what to mark the status as when
> I'm done.

Candidate status means you've had other people look over your
work and you don't think I'll find anything wrong with it.

When a document reaches candidate status, it's to be reviewed
by a team coordinator.  Right now, that means me.  Since final
reviews happen late, they can't involve major changes.  Things
need to be basically done already.  I really want to reply to
final review requests with two letters: OK.

--
Shaun