openstack-doc-core team mailing list archive

[Lana Brindley <openstack@xxxxxxxxxxxxxxxx>]

Hi core team!

There was some discussion at Summit about our review rigour, and about how we can make improvements to our existing review system. There are some high level notes in my email here: http://lists.openstack.org/pipermail/openstack-docs/2016-October/009268.html

Anne had an intriguing proposal to run a special day (possibly over a holiday weekend) where we allow anything and everything to pass, in an effort to get new contributors. Personally, I think that might be too risky for the heart health of our cores, but I do like the idea of dramatically lowering the bar for contributions. We are somewhat notorious within the wider OpenStack community as being overly nitpicky on our reviews. I appreciate that some of that is about being good editors, and nitpicking pretty much goes with the tech writing territory (I am as guilty as anyone).  However, I think we can all make a concerted effort to try and tackle this.

We've often said it in a casual sense, but I'd like to propose that we formalise the "is it better than what we already have" rule, (mentioned here: http://docs.openstack.org/contributor-guide/docs-review.html#core-reviewer-responsibilities) so that we prioritise improvements over spelling and grammar.

This can be balanced by the fact that it is now extremely easy to fix nits as you are reviewing, with the inline editing tool. It is often quicker and easier to edit a patch directly to fix typos than it is to write a comment, -1, and wait for the original author.

What do you think? Let's get this discussion rolling, and once we have some solid ideas amongst this group, we'll widen the conversation to the whole team, and update the Contributor Guide accordingly.

Cheers,
Lana

-- 
Lana Brindley
Technical Writer
Rackspace Cloud Builders Australia
http://lanabrindley.com

Attachment: signature.asc
Description: OpenPGP digital signature