On Tue, Nov 8, 2016 at 5:42 AM, Alexandra Settle < alexandra.set...@rackspace.com> wrote:
> 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? > It really is a learned skill, and we need to keep coaching each other and learning as we go. There's a line, it's hard to learn, and all I'm asking us to do is move the culture towards "just land it if it's better than what we had," especially for technical accuracy. > > 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’? > Yes, I would propose the action to be "edit in your web browser and then land the patch" instead of "comment and wait for the other person to patch their patch." This is completely opposite of what we do in OpenStack and it has gotten crazy out there. > 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? > > Again, you're going to have to both teach and learn what is acceptable. For starters, absolutely value technical accuracy above all else. Technical questions are not nitpicking. I don't see this push towards merging first as a knock against the contributor guide. It serves a purpose, as a teaching tool, and even if you edit-and-merge you can comment with a link to the contributor guide to teach why you did the edit you did. 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? > It's funny, I think that nitpicking in review without any cleanup makes us look secretarial, because instead of landing docs and adding value, we're not landing docs that add any value. By valuing technical accuracy and value above all else we move up the value chain while getting more contributors who feel like they are making a difference. > > 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. > I suggest we try it and see what chaos ensues with these guidelines: 1. If it's technically accurate, merge it. If it fixes a bug correctly, merge it. 2. If it's accurate and correct but could be written better, edit, then merge it with a comment to coach the person how the writing could be better. 3. If it's not the kind of patch we want for the docs, explain that in the review and also follow up to make sure the person doesn't feel rejected outright. Take ownership of the coaching areas more than the "this is wrong and here's why" aspect. (I'm not saying your reviews are like that, mind you, I just want ownership of the growth of contributors and the accurate doc base, not ownership of "it meets our English standards.") Do those written guidelines help? Anne > Cheers, > > Alex > > On 11/8/16, 1:09 AM, "Openstack-doc-core on behalf of Lana Brindley" > <openstack-doc-core-bounces+alexandra.settle=rackspace. > c...@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 > -- Anne Gentle www.justwriteclick.com
-- 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
