Update and expand Contribute Guide and README

[toasterlovin]

When I made my first contribution, which was to add only 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 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.

Some 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. [IGNORE THIS, FIXED IN A LATER COMMIT] 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...

[mauritslamers]

Just replying on your description of problems you had:
I completely agree on everything you write and also fits with the stuff we have been discussing in the IRC channel.
Things should be much much easier and especially better documented.

I am not sure whether trying to spend time on the ruby system is a wise investment of time.

Thanks a lot for your investment and your commitment!!

[toasterlovin]

@mauritslamers:

Yes, yes, yes. Documentation is the key to getting people to use something. Most people just aren't at the level where they can drill into source code to learn something. They need guides, screencasts, blog posts, etc.

When deciding which in-browser JavaScript framework to learn, I was actually fairly turned off by the state of the documentation for Sproutcore as compared to, say, Ruby on Rails. Three things made me decide to learn Sproutcore instead of Ember or Backbone:

1. The documentation for those seemed even worse
2. Things like "BREAKING CHANGES" all over Ember's data store GitHub repo.
3. I decided that helping out with the Sproutcore documentation would be a really good way for me to learn Sproutcore thoroughly (if you can teach something, you have mastered it)

Anyway, I feel happy with the novice accessibility of my updates to the Contribute Guide, but I'm very unhappy that a novice would have to go through so many steps and invest so much time just to fix a typo or error in one of the guides. It would be so nice if there were an easier way to edit and maintain these. A couple of thoughts along this vein:

1. A wiki with in-page editing and previewing seems like the ideal tool to me.
2. Perhaps a little on-page widget so people can highlight a bit of text and add a quick comment or suggestion would be useful.

In my opinion, if we want people to help, we need the lowest barrier to entry possible. I think that the ideal is something that handles editing and previewing in-page. Maybe a middle ground is a way for people to leave comments on pages. I think the least ideal is a git based workflow (on the user-facing side, at least; a git backend is fine).

[dcporter]

Hi Rico,

Just to echo Maurits, our documentation is an area where we're hoping to exert some effort, so your contributions are very welcome! Maurits is in the process of moving the build tools to an SC-on-node platform, hence his comment about the ruby tools not being worth pursuing.

I believe we're also in the process of developing a wiki, which will contain lighter-weight content than the guides, and of course be dramatically easier to edit. I agree wholeheartedly that having a section of easy-to-edit wiki-style documentation is great on a lot of fronts, especially lowering the barrier for community contribution. The current sticking point is the choice of wiki platform; if you have any insight on that please let us know.

Again, thanks much for your thoughts; they dovetail very closely with where we are taking the community, and your contributions are crucial!

Thanks,
Dave

[toasterlovin]

@dcporter

RE: build tools - Yup, I realized that all I needed to do to avoid the issues with the guides gem indexer is to add spaces at the beginning of the line that it was choking on, so that's been done and added as another commit.

RE: wiki software - No experience with any. I would say, though, that something which uses Markdown would be best. Not that Textile is bad or anything, but I think people are more likely to have encountered Markdown, since it is used at GitHub and Stack Overflow.

[dcporter]

Agreed that markdown is great; however Maurits is already hosting something which uses something else. Looks like we're gonna go with that for now. Here's the link: http://devmt.hku.nl/~sproutcore/doku.php

Further discussion is presently ongoing on IRC if you'd like to jump on!

[topherfangio]

Quick question for @dcporter or @mauritslamers : Is the wiki linked in this thread (http://devmt.hku.nl/~sproutcore/doku.php) still being maintained? If not, could we consider moving it to a wiki hosted by GitHub (ideally on the main SproutCore project)?

[dcporter]

@mauritslamers can speak to the wiki's status; the idea of using the github wiki was suggested previously and shot down by @publickeating because that wiki is for information about the repo / project, not how to use sproutcore.

[mauritslamers]

Yes, the wiki is still actively maintained, but at the moment I don't have much time to spend writing stuff.
I set up that wiki (and am hosting it still) in the Strobe era because of the lack of documentation then and because we (enquora and I) didn't particularly like the way the guides were developing.
Because this is a wiki with ACL support, it allows control over who is editing what, and that capacity it can serve as a kind of prototype for the CMS style of documentation we have been talking about. Thoughts?

[topherfangio]

I think the wiki is a good idea, but I think it should be hosted somewhere a little more accessible by project owners/maintainers in case something breaks and we need to fix it. Additionally, it was fairly slow for me when I was using it last night, but I'm sure most of the existing sites are slow for you and others not in the US. It would be fantastic if we could host static files on a global CDN, but I'm pretty sure this isn't possible with any existing wiki that I know of...

Last question/thought: does your wiki support textile or markdown?

[mauritslamers]

Dokuwiki has a custom text format, but I think it might be sort of similar to markdown or textile, or parseable enough to to an automatic conversion.
I think that Dokuwiki might actually be deployable on a CDN because it doesn't use a database, but plain text files.