Open Stack

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.

The result is twofold:
     a)  The patch is delayed, so users don't have the benefit of the 
information.
     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.

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.

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.

----  Nick