Re: contributing instructions are misleading!

[Graham Percival]

On Wed, Dec 11, 2013 at 01:48:54PM +0100, Janek Warchoł wrote:
> PS ccing to Graham because he might be interested to know that
> Someone(TM) is doing Something(TM) to help new contributors!

Sorry, this awoke Grumpy Graham.

Reorganizing the CG is very much a "something should be done, this
is something, so can somebody else do this thing".

> After a good deal of thinking, here's how i think CG should be
> structured.

More thinking and discussion than we had the previous 4 times we
reorganized the CG?

> The first chapter should contain everything that a
> contributor should know

... so chapter 1 will be 50 pages?

> (including ho to upload patches for review), and if possible it
> shouldn't contain optional information (for example not everyone
> needs to use LilyDev, so this should be in a separate chapter).

Is there any solid evidence that a serious contributor finds it
difficult to skip over section 2.1 if it's not relevant?

> 1) Introduction and Quick start
>    * setting up development environment
>      - link to Lilydev
>      - env variables
>      - "Initializing a repository"
>      - installing git-cl
>      - git setup tips (i.e. showing branch in prompt)

But new developers don't need to know anything in there, other
than the link to lilydev.  Lilydev and git-cl handle everything
else.  So your goal of "everything that a contributor should know
and shouldn't contain optional information" already failed.


I agree that it's really bad that the CG encouraged people to send
stuff to the Frogs list.  A fix for that was certainly needed.
That doesn't imply that yet another round of reorganizing the CG
is needed.  It would be much more useful to go through the CG and
update the content as necessary.

- Graham