openstack-doc-core team mailing list archive

[Alexandra Settle <alexandra.settle@xxxxxxxxxxxxx>]

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.com@xxxxxxxxxxxxxxxxxxx on behalf of openstack@xxxxxxxxxxxxxxxx> 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 abuse@xxxxxxxxxxxxx and delete the original message. Your cooperation is appreciated.