Re: we now have "lilypond" organization on GitHub

[James]

On 24 September 2013 15:53, Joseph Rushton Wakeling <address@hidden> wrote:

On 23/09/13 12:59, Graham Percival wrote:

Reviewing patches?  Explaining why we reject a patch (I don't
think we can fairly reject a patch unless we explain why)?  Those
are significant costs.

What are the most common reasons for doc patch rejection?

* Poor English syntax or ambiguous explanations (depends on the Manual - Notation Reference and Learning Manual are two different beasts - see the Contributor's Guide),
* Examples that don't compile (break make doc) - this is more likely when users try to submit snippets incorrectly. I will admit the snippet part of the doc is complex but that si more to do with the fact that it has to both cater for documentation AND a website.
* Examples that contain too many overrides - goes against Documentation Policy (again see Contributors guide).

The fact our documentation is (even if I do say so myself) very comprehensive, is precisely because patches get reviewed and discussed before they are incorporated (this wouldn't happen with a wiki). Things like users reporting typos and simple changes often get fixed by other developers very quickly, if not tracker items get put up and it isn't long before they get fixed.

Yes it would be nice to have more contributors (I was one of the main documentation editors myself - I have no programming experience but can handle texinfo syntax - I now help manage patch testing and branch merging using LilyDev which I also help to maintain. In fact I think I am a good test-case for someone who had no git experience, no concept of what texinfo was and cannot code, yet am still here 3 years on contributing to the cause. Graham Percival had been managing the documentation for many, many (many) years so has very good empirical evidence of what does and doesn't work with regard to documentation.

You would do well to look over the dev lists for the last few years (look for strings like 'wiki' and 'GOP' and 'Documentation project') to see this kind of discussion you are bringing up has been beaten to death many, many times. A Wiki is a terrible idea by the way - if you look at the documentation and how it is built and distributed (PDF, Website all automatically built and because of the way it is structured all examples are kept consistent with the latest syntax, there are automatic cross refernences, indexing - all the good stuff Tex was designed to do that a Wiki frankly would not be able to do without a lot of work). The 'build and they shall come' approach simply has been proven not to work with our documentation.

As Phil has said in another email, if you feel so strong about something then go for it, show the dev team how it could work better than it does now. I guess some of the more older devs are often tired about the same things coming up over and over but no one has yet really shown that it could work. Those that are working on LilyPond already spend as much time as they can on coding or helping test patches etc.

We could do with others (like yourself?) to try other things and report back. I'm curious for instance to see what Janek comes up with, with his 'Git' discussions.

James