Open Stack

Hi all,
So pleased with the great throughput we're seeing with our new core
reviewers on docs. Thanks all!

I noticed that the openstack-dev list has pointed to a wiki page for review
guidelines for all code projects to follow at
https://wiki.openstack.org/wiki/ReviewChecklist. We definitely have similar
guidelines and consistency and tests are at the heart of it. But I think we
can build some more guidelines for reviews for docs, since we are a bit
different. We need speed and accuracy to prevail, while holding a line for
quality and consistency considerations.

Writers become better writers by continually editing and refining. I think
we do a good job at this, but we are also serving a non-writing set of
collaborators. So how about some additional guidelines for our reviewers?

 - If you have nits to pick, fix them yourself rather than making the
contributor do it, unless the contributor prefers to learn by being edited
(I have seen this over and over in my writing, that I'm a better writer
after entering someone else's edits).
 - Reviewers, let's constantly police ourselves for over-nitpicking when
technical accuracy is our main goal.
- Let's still recognize the quality rise that better editing gives us.
- As the release gets closer, speed matters over editing as long as it's
consistent.

There are a few things going on to help with this balancing act:
- The O'Reilly custom edit means we can reliably believe that all nits have
been picked, but we also have to ensure crap doesn't nudge in. :)
- I'm having a Rackspace editor work with a Rackspace writer to do a deep
edit on the End User Guide, that patch will land soon.
- I'm seeking ways to get a style guide beyond just our Conventions wiki
page to help us all edit with confidence that consistency will prevail.

Thoughts? I'll put this info in a wiki page for reviewer guidance once we
all agree on the basics.

Thanks,
Anne
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140401/1c6a3a43/attachment.html>