sproutcore/guides — pull request #123 by ricolicious (2012-10-27 18:34:47+00:00)
Title: Update and expand Contribute Guide and README

When I made my [first contribution](https://github.com/sproutcore/guides/pull/122), which was to add a measly 3 words to one of the guides, it took me a long time to figure out exactly what I needed to do to add my 3 words.

The reason it took me so long is because the Contribute Guide and README are written from the point of view of somebody who already has a pretty good idea of how Git, GitHub, Forks, Topic Branches & Pull Requests work. Somebody who doesn't already know all that stuff could piece it all together, but they would have to be __very__ motivated (as I was).

I can see that understanding the Git workflow is a reasonable and necessary barrier to making contributions to the SproutCore source code, but the Guides are, almost by definition, used by newbies, who are less likely to know the ins and outs of Git, but who could very easily spot a typo or error.

Anyway, I thought we could do better. This is my take on what these two documents should be.

A couple of things I wanted some input on:

1. We are asking people to go the the SproutCore-Dev Google Group for questions, but that place is (recently, at least) mostly spam. Should we be sending people to the main SproutCore Google Group instead?

2. Also, I would ask the same question about the Sproutcore-Dev IRC channel. I haven't been on it, but is that still the best place to send people, or should they go to the main IRC channel?

3. The "h3. Topics Should Use h3" text in the sample Textile file in the "Create a New Guide" subsection causes the guide indexer to break. The indexer is the part of the guides gem that adds numbers to the sections and creates the index on the left-hand sidebar. I am working on a fix for the guides gem, but that'll take me some time. Any thoughts before I put a bunch of time into this?

4. Please, any other thoughts are appreciated. This is my first guide...