balderdashy/sails-docs — pull request #366 by LoveIsGrief (2014-12-14 19:58:39+00:00)
Title: Getting started guide

Hello,

I recently got started with sails and while the docs are pretty good (better than it was a few months ago), I was still kind of lost and didn't know where to start. The intro video is a few versions behind.
Since Sails seems to be Rails for Javascript, I decided to transcribe the [rails guide](http://edgeguides.rubyonrails.org/getting_started.html) and indeed, I learned quite a bit about the inner workings of Sails.

The rails guide is **not** about making a single page application, but about understanding the inner workings of rails. I simply did the same with sails.

This is a **premature** pull-request as not everything is transcribed, but I would like to have comments on this. Maybe I'm going off course, maybe not everything is in the guide, maybe something could be done better. Constructive criticism I seek.

Reimplement blueprints or write an intro using them?
=========================================

Personally, I'm against using blueprints in a "getting started" guide. I believe people should know a little bit more about what's going on behind the scenes in order to write their own actions.
I'm a beginner as well, so if learning that is unnecessary, please do help write the guide :) Also please explain why, as I'm sure other would ask the same thing (people coming from rails or similar frameworks).

This guide reimplements blueprints for the reasons in the first paragraph.

REST - GET+POST or websockets?
============================

At the moment my biggest concern is REST. When sending **non-AJAX** requests to the backend, I see only 2 options:

1.) Form methods: GET, POST

That will allow routes like /:model/:action/(:id) and all can be done with GET and POST. That leaves out PUT and DELETE however. So... kind of REST, but not totally.

2.) websockets

This will force us to add custom javascript code to the guide in order to listen to events on buttons, collect form info and then send a socket message. I am very much against this as it will add more stuff to understand that isn't in the sails conventions - anybody can implement another way of doing it (e.g AJAX).
I would propose a separate tutorial e.g "Getting started part 2: Single page applications and websockets".

___________________

For now, I will continue with the getting started guide while waiting for constructive feedback.

Cheers!

P.S How do I get links like
```markdown
![EloquentJavascript][EloquentJavascript].

[EloquentJavascript]: http://eloquentjavascript.net/ "Eloquent Javascript"
```
to work?