In theory I liked Anne’s idea, but I admit my poor heart probably could not
handle the amount of technical debt we’d essentially be lumping upon ourselves.
With that in mind, I think that’s a fair comment that we lower the barrier to
entry. I know I am terrible for nitpicking a patch within an inch of its life.
But I suppose that raises the question, where’s the line?
We have the contributor guide for a reason – if someone fails to follow it are
we to start editing the patches ourselves to make the contributor feel at ease,
or are we just to let it through when it is ‘acceptable’?
If the second option is true, what counts as ‘acceptable’? Will we no longer be
relying as heavily on the contributor guide to ‘guide’ us?
Playing devil’s advocate, say we lower the barrier to entry and we use the edit
function more freely – are we becoming the secretaries of the OpenStack doc
world? What line in the sand do we draw for cleaning up people’s
spelling/grammar errors?
Sorry for all the questions! Just many thoughts running through my head. Let it
be known that I definitely think this is a good idea! But I suggest some lines
are drawn so we are all clearly on the same page.
Cheers,
Alex
On 11/8/16, 1:09 AM, "Openstack-doc-core on behalf of Lana Brindley"
<openstack-doc-core-bounces+alexandra.settle=rackspace....@lists.launchpad.net
on behalf of openst...@lanabrindley.com> wrote:
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
________________________________
Rackspace Limited is a company registered in England & Wales (company
registered number 03897010) whose registered office is at 5 Millington Road,
Hyde Park Hayes, Middlesex UB3 4AZ. Rackspace Limited privacy policy can be
viewed at www.rackspace.co.uk/legal/privacy-policy - This e-mail message may
contain confidential or privileged information intended for the recipient. Any
dissemination, distribution or copying of the enclosed material is prohibited.
If you receive this transmission in error, please notify us immediately by
e-mail at ab...@rackspace.com and delete the original message. Your cooperation
is appreciated.
--
Mailing list: https://launchpad.net/~openstack-doc-core
Post to : openstack-doc-core@lists.launchpad.net
Unsubscribe : https://launchpad.net/~openstack-doc-core
More help : https://help.launchpad.net/ListHelp
