Open Stack

On 02/20/2015 06:52 PM, Nick Chase wrote:
> I'd like to take a moment on something that's been bugging me for a
> while, so I'll ask that everyone please just hear me out with an open
> mind before hitting "send" (or "delete", for that matter).
> 
> My interest, in this case, is in improving the experience of both
> contributors and readers.
> 
> Let me start by saying that I'm all for making sure that the
> documentation is completely correct, not just in terms of the
> technology, but also in terms of terminology, conventions, and so on. 
> So please don't think I'm going to suggest that we let things get
> sloppy.  I'm not.  I think it's terrific that we have people who are
> passionate about accuracy, language, and even punctuation. I salute you
> all.
> 
> However.
> 
> Probably everyone here has seen situations where you can have a
> perfectly good patch that accomplishes a lot of good and that everyone
> agrees is ready -- except one person who objects to something minor,
> such as how something's named, or a markup convention, or even
> punctuation.  Despite the fact that this "defect" doesn't affect the
> content, its utility, its readability, or even (in many cases) the
> rendering, this person will then -1 the patch.

We have a standard for our documentation and thus I feel that we should
bring people up to speed in a good way.

If it's only a minor thing, I sometimes patch others patches - and if
somebody asks for help on how to do it, I definitely will give the help
that the person needs.

But we have to tell a contributor about our conventions to have high
quality standards - and I agree that we should do this in a nice way.

> The result is twofold:
>     a)  The patch is delayed, so users don't have the benefit of the
> information.
	
Which patch is triggering that that has so important information in it
that it needs to go out half way?

>     b)  The contributor is frustrated.
> 
> As we move into the "big tent" role of "enablers" rather than
> exclusively as "doers" this is going to become increasingly problematic
> as we alienate the projects that are trying to do the right thing by
> writing their own documentation.

Even in the big tent OpenStack discussion, projects have many roles that
they enforce and request from every newcomer.

> To solve this problem, I would like to suggest that rather than -1'ing
> the patch, these patches be approved with an understanding that a
> separate bug will be filed to "clean up" the content.

Who will clean it up and when? I don't like accumulating technical debt
that nobody is going to pay.

> The result, in this case, is threefold:
>     a)  The patch is ready quickly, so users have the benefit of the
> information.
>     b)  The contributor is happy, and feels accomplished, and is more
> likely to contribute again.
>     c)  We have a bigger supply of the rare "low hanging fruit" bugs,
> which we need to entice new contributors.
> 
> I think this would be an important policy to implement going forward.

I don't think this is thought through completely,

Andreas
-- 
 Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi
  SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
   GF: Felix Imendörffer, Jane Smithard, Jennifer Guild, Dilip Upmanyu,
       Graham Norton, HRB 21284 (AG Nürnberg)
    GPG fingerprint = 93A3 365E CE47 B889 DF7F  FED1 389A 563C C272 A126