Re: we now have "lilypond" organization on GitHub

[Joseph Rushton Wakeling]

On 24/09/13 14:22, Graham Percival wrote:
> Suppose somebody sends you a bad patch that would take you 5
> minutes to re-implement from scratch.  Do you:
>
> 1) spend 30 minutes explaining how to fix the patch
> 2) tell them to go screw themselves
> 3) ignore the patch silently and give the person no indication of
> what went wrong.
>
> I've done #1.  I spent a WHOLE YEAR doing #1.  It was an
> experiment.  I was absolutely committed to teaching people how to
> do docs.  However, #1 gives a net penalty of 25 minutes.
>
> "oh, but maybe that person will do better next time"
>
> Yes.  In many cases they did.  So the next patch only took me 20
> minutes to explain how to fix it.  The one after that took 10
> minutes.  Then, on the 4th patch, it was ok without needing any
> fixes.  So... currently we're at a deficit of 45 minutes.  If they
> send in another 9 patches, each one doing a 5-minute fix, then
> we've broken even.

If the problem is so persistent, I would suggest that this is a fundamental 
issue with the usability of your documentation tools and submission procesures, 
and that _this_ is the issue you consider fixing.

Look at it this way.  If you were starting a new software project from scratch, 
now, would you choose TeXinfo as your documentation format?  Almost certainly 
not -- you'd probably create a MediaWiki instance and have people contribute 
there, and write a few plugins that would enable Lilypond input to be entered 
into the Wiki page and auto-generated into the desired PNG for display.

Now, do you think you'd be having half the problems you have with tweaks to that 
wiki, as you are having with patches to your TeXinfo docs?  Almost certainly 
not, because (i) the wiki gives immediate preview feedback during editing so 
that users can _see_ that their tweaks don't work; (ii) wiki markup is much 
simpler than TeXinfo; (iii) wiki markup is much more widely used these days, so 
many more people are already familiar with it; (iv) contributing to a wiki 
doesn't have to involve the command-line complication of handling git or any 
other VCS tool.

TL;DR I think you spent a whole year _solving the wrong problem_, because you 
were attempting to train people to become long-term contributors who could work 
round the issues of the existing tools, rather than solving the real issue, 
which is:

   "How can I get things set up so that docs contributors GET IT RIGHT FIRST
   TIME even if they've never contributed to Lilypond docs before?"  [*]

[* Corollary: "... and so that if they get it wrong, they can see it and work 
out how to fix it themselves before it becomes my problem."]


> Your "suppose" and "maybe" does not trump my empirical evidence.

Your empirical evidence reflects the fact that your docs setup makes it 
difficult for the 75% to easily create value.