Open Stack

Nick, 

Thanks for this. 

I think your suggested policy is a good one and I hope we can find a good way to implement it.

Who is responsible for creating the bug for the "clean up" work? The commenter or the patch owner? How will we enforce this? 

The risk we take is that these "clean up" tasks never get reported or completed. 

(And honestly, having people address "clean up" comments immediately is not that time-consuming and turns people into better writers who need to complete less "clean up" as time goes by. Just as detailed code reviews make developers better developers.)

diane




---- Nick Chase <nchase at mirantis.com> 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.
> 
> 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
> 
> _______________________________________________
> OpenStack-docs mailing list
> OpenStack-docs at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs