openstack-doc-core team mailing list archive

[Anne Gentle <annegentle@xxxxxxxxxxxxxxxxxx>]

On Thu, Nov 17, 2016 at 12:43 AM, Andreas Jaeger <aj@xxxxxxxx> wrote:

> On 11/08/2016 12:42 PM, Alexandra Settle 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?
> >
> > 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.
>
>
> I think we have to balance. Looking for example at
> https://review.openstack.org/398309 . Here's my reasoning:
>
> +1 It's a completely new change, so better than what we have before
> +0 It does not build, we could fix it easily
> -1 But it's soo inconsistent that bringing it up to the quality level
> would requite
> -2 Not taking it yet since no contact is added to third-party vendor
> list. We agreed to not take these.
>
> So, gave a -1 with links to the above - and wait.
>
> If it were two or three small edits, I would have done it,
>


Yes, this is even better guidance -- and how much time you have to fix
while reviewing is also a piece of this (because we could end up slowing
down review time because of having to take time to fix). Still, by choosing
to focus on leveling up people rather than words, we can see what that
shift could do. If it doesn't give us what we want (better docs, more
contributions) then we try something else.

Anne



>
> Andreas
>
> > 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.
> >
>
>
> --
>  Andreas Jaeger aj@{suse.com,opensuse.org} Twitter: jaegerandi
>   SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
>    GF: Felix Imendörffer, Jane Smithard, Graham Norton,
>        HRB 21284 (AG Nürnberg)
>     GPG fingerprint = 93A3 365E CE47 B889 DF7F  FED1 389A 563C C272 A126
>
>
> --
> Mailing list: https://launchpad.net/~openstack-doc-core
> Post to     : openstack-doc-core@xxxxxxxxxxxxxxxxxxx
> Unsubscribe : https://launchpad.net/~openstack-doc-core
> More help   : https://help.launchpad.net/ListHelp
>



-- 
Anne Gentle
www.justwriteclick.com