[Yum-devel] fastestmirror plugin documentaion patch

[seth vidal]

On Thu, 2007-12-13 at 15:21 +0100, Florian Festi wrote:
> Hi!
> 
>  > I am a newbie to yum-development. I have written complete documentation
>  > for the fastestmirror Yum plugin. I am not sure how to commit it to the
>  > original code of the fastestmirror. Please help me to commit the code.
> 
> You should work on the current development version. See 
> http://linux.duke.edu/projects/yum/scm.ptml how to get them.
> 
> We use git as source management system. So you'll have to learn git to some 
> extend.

no he doesn't. He can just download the tree and submit patches via
email. Learning git is a barrier to participation and should not be
considered a requirement to helping out with yum.



> Such patches are the only legitimate format for sending code to the mailing 
> list as it is the only way that it is clear which version was changed, avoid 
> encoding problem, add a proper commit message and be easy to import into the 
> upstream git repository again.

No, they're not. You can generate patches using plain diff. Don't put
barriers up like this and please don't act like you're speaking for
everyone.



> OK, now to your changes:
> 
> For my personal taste they are a bit too verbose. Doc strings should give 
> the reader a short summary of the things he really needs to know. Avoid 
> stating the obvious - like that there are no parameters. On the other hand I 
> like that you state that the function uses global variables - a cause for a 
> lot of fun if missed. But as most function do so you can consider stating 
> this at the module level. Same applies to the description of the global 
> variables.

Stating the obvious is what documentation is about. Being clever in docs
just means someone else is confused.



> As a general hint I'd ask you to shorten your language a bit. The shorter 
> you can express what you want to/need to say the faster can developers read 
> and understand what this piece of code is about. No one is looking for a 
> pleasant reading experience but for a short info that's easy to read and to 
> keep up to date. There is no need for using whole English sentences. Terms 
> like "This function" are simply superfluous - "It uses global variables to
>   communicate with other functions." can be shorten to "uses global variables".

Except it's a crappy sentence and doesn't explain WHY the globals are
there, which is a better sentence. Verbosity in documentation, provided
it's not like the god-awful dissertations in the git documentation, is a
plus. Clarity is an even bigger plus.

-sv