Outline for an official tutorial

[newz2000]

Many successful projects have more than just reference documentation, they have tutorials and helpful guides. These are both items that are missing from the official Sails docs.

Here is a possible outline. I am not qualified to write all of this but am happy to help by creating stubbed documentation and filling in holes where I can.

Story:

User is guided through the process of building a website offering daily deals, similar to Groupon. The website will be mostly server-rendered HTML with RESTful endpoints allowing the user the opportunity to use client-side MVC tools as they desire.

Goals:

1. Each tutorial can be completed in about 30 minutes by someone who knows Javascript and has already followed the Getting Started guide to install Sails.js and create the Hello World application.
2. Tutorials will always be up-to-date with the latest version of Sails.js
3. Examples will show only the simplest way to accomplish a task that aligns with the best practices suggested by the developers - side bar items will point out other potential ways to accomplish something with links to reference documentation if a more complicated method is sometimes advisable
4. Tutorials will focus on teaching Sails.js - Angular, jQuery, Sass, MongoDB, etc may be mentioned but the goal is for people to learn Sails.js not those other tools which have their own documentation.
5. Example code can be copy/pasted but should be short enough that a user can type them out in order for them to become more familiar with the code and have the ability to modify it for their own uses.

   Tutorial Part 1

6. Create a project using the command line tools
7. Create the models for storing daily deal data
   1. Title
   2. Slug
   3. Body text
   4. Link
   5. Created date
   6. Expiration date
8. Create a view (or etc) with an HTML form that POSTs to the database to enter new deals
9. Create a view (or etc) that renders a home page of deals sorted with most recent first
10. Use the static asset pipeline for stylesheets

    Tutorial Part 2

11. Add a model for users
    1. Username
    2. Password / hashed password
    3. canCreate
    4. isFeatured (featured users will get a special badge next to their name)
    5. Email
12. Create a model related to Users that lists the deals they've claimed
    1. Reference to Users
    2. Reference to Deals
    3. Created date
13. Create registration, login and logout forms
14. Require authentication and canCreate in order to view the form or create new deals (Policies)
15. Add fields to the daily deals model
    1. Remaining deals available
    2. Featured deal
16. Require users to login in order to click the link to the deal
17. Each time someone clicks the link to the deal, the "remaining deals available" is decremented and an entry in the "claimed deals" table is created

    Tutorial Part 3

18. Update model to allow image attachments
19. Update POST form to enable file uploads and to attach image to posts
20. Create a link on the deals page allowing filtering of deals
    1. Deals with less than 5 available
    2. Deals by user
    3. Featured deal
21. Allow those who post deals to remove their deals (by changing the expiration date)
22. Allow those who claimed a deal to unclaim it by deleting the entry in the Claimed model and incrementing the available deals
23. Use Websockets to:
    1. Show new deals on the website instantly
    2. Update available deal count
    3. Hide deals when they are expired

       Tutorial Part 4

24. Write unit tests for features described above
25. Introduce helper functions and time-savers, maybe using Passport or other Express middleware
26. Deployment options - Heroku is one of the lowest friction deployment platforms, maybe use it as the example
27. Sending e-mails to deal owners whenever someone claims a deal

[arcseldon]

Great starting point. Based on recent experience writing a comprehensive commercial application with Sails 0.10.5, and listening to others frequently asking the same sorts of questions, here are few extra thoughts where I found documentation thin:

A section on productionizing the deliverable would be nice. Just some ideas, MongoDB configuration with clustering for fault tolerance (slightly DB specific perhaps), SSL setup (Heroku would not require client certs etc), SailsJS fault tolerance with say forever / cluster etc, multiple environments configuration, integration with say Continuous Integration environment such as CodeShip / Travis.

A section devoted to security, from simple basic authentication with express using local strategy, to API Tokens with JSON Web Tokens (JWT).

Would like to see usage of inheritance in the Controllers and Models, example functional test suite with Mocha (before / after loading and lowering sails app), best practices for writing bootstrap fixtures with moderate amounts of data (recommended promises / async pattern etc), extending the Grunt tasks to handle JSHint, MochaTest etc. A domain model that exercises all the core association multiplicities (one to one, one to many, many to many, self-referencing table and dealing with async tree recursion both up and down the tree structure). Soft delete feature, explicitly writing CRUD operations in controllers while retaining criteria queries for get ops. Section on developer productivity - using sails console, nodemon for live reloads, how to actually inspect the SQL being generated by Waterline in MySQL etc (again db specific). Controversial: a tutorial on writing an entire SailsJS app with CoffeeScript (server / client side, including APIs, Models and Config. :)

.

[newz2000]

Great points. Some of those definitely need to be in there. The only examples I can see at a quick glance that would probably not fit in with my line of thinking would be the SSL stuff, and probably Travis. I think your controversial point is also probably fit for a different kind of documentation. I say these because of Goal 4. SSL is important for many apps, but you don't need to understand it to learn Sails.js.

The Database points are an interesting problem. Being straightforward, I've not wrapped my head around Waterline. I've used it now with both PostgreSQL and MongoDB and in both cases it worked without me needing to do much. I didn't leverage anything advanced in either of these cases.

My inclination would be to show how to configure the database adapters but otherwise just stick to features that should work seamlessly regardless of the database. Then write additional documentation on how to do cool stuff with your database of choice. It's possible, maybe even probable, that the existing ORM documentation included in Sails would provide that.

Since Sails.js is such a comprehensive framework, my suggestion for the first round of official documentation is to ruthlessly focus on the best practices for using Sails.js's included components, except where that's not possible (sending e-mails for example).

Also note that I think Ruby on Rails has a good thing going with their guides. I would suggest that some topics need a dedicated tutorial, which would be a guide. Each guide would probably be a one-page document that walks you through an example scenario that helps someone master one of the more nuanced aspects of Sails.

[newz2000]

Tutorial 2 feels lengthy to me, and I just realized that session support would need to be added to that, wouldn't it? It's going to have to go in there either for tutorial 2 or 3.

[nuclear-icebreaker]

@newz2000 This is kind of tutorial I would like to have to become more involved in community as intermediate user. For now I am struggling to catch up with really simple tasks. One place more to get inspiration for documentation structure is cakephp cookbook. For me it was good starting point to start coding CakePHP.

I think SSL setup mentioned by @arcseldon would help, but TRAVIS for me seams to be more out of scope of Sails tutorial.

[gihrig]

Just want to comment that this is vital. I've just given up on Sails for use in a professional, public facing project, after about 100 hrs of intense research into the docs, SO, YT, and others, reviewing source code and much trial and error. I have overcome many hurdles, but, overall the getting started 'friction' is more than I can tolerate.

For reference, I have years of Java, PHP and other experience, I've been working in Node Javascript intensively for a few months, and am tentatively comfortable with Node and Express.

This is not meant to be a complaint, downgrade or criticism, but more supporting evidence for the need of a comprehensive intermediate to advanced level tutorial as @newz2000 has outlined.

As a start, for me at least, simply having the tutorial's subject application available would have made the difference between success and failure. Perhaps as a first step, the core team could whip up this app. Having that, well commented, I think the community could handle creating and polishing the tutorial.

[blah238]

:+1:

One very important aspect missing from this outline is how to structure code in a modular, composable way.

[dancancro]

This may or may not be useful to you. It's my collection of things to use when starting a web application. Among them are many courses. Mouse over the name to see a table of contents for each one. Have a look at the comparisons between them. Browse the list of features that they demonstrate. Check out the "How do I... " section. Good luck!

http://www.dancancro.com/comparison-of-angularjs-application-starters/

[arcseldon]

@gihrig +1 Definitely in favour of a comprehensive (beyond 101, hello world style) reference Sails application that showcases all the primary feature sets. To be useful to commercial development in the real world, it should address Production aspects too. Good documentation is no doubt valuable but a well written application containing the mainstream features is potentially more so. And yes, there would need to be a commitment to maintenance and ensuring it is upgraded as Sails evolves.

[rattrayalex]

Thanks for sharing @gihrig !

For what its worth, I'm personally not convinced reference applications can provide as much value as a well written guide/tutorial.

Reading code to learn a framework can be frustrating because you don't know what's idiosyncratic to the example app, what's core to usage of the framework, and how important various framework features are or what their alternatives might have been.

A well written tutorial and guide can discuss several important nuances in a single sentence. Concepts are just better consumed in prose; examples are helpful but not best for giving overviews. On Oct 23, 2014 9:52 AM, "arcseldon" notifications@github.com wrote:

@gihrig https://github.com/gihrig +1 Definitely in favour of a comprehensive (beyond 101, hello world style) reference Sails application that showcases all the primary feature sets. To be useful to commercial development in the real world, it should address Production aspects too. Good documentation is no doubt valuable but a well written application containing the mainstream features is potentially more so. And yes, there would need to be a commitment to maintenance and ensuring it is upgraded as Sails evolves.

— Reply to this email directly or view it on GitHub https://github.com/balderdashy/sails-docs/issues/317#issuecomment-60182574 .

[arcseldon]

Please also refer to Sails development is outpacing documentation #2325 to get some context to where this post came from.

It may be that different developers have different views over what the tutorials audience represents. If this is beginner level, giving overviews etc and explaining the basics, then the following resources are a great starting point:

Sails - Getting Started:

Watch the 15 mins intro on the official Sails website:

Sails

Read the SailsJS documentation:

Sails documentation

Good intro building a simple chat app:

Building a Simple Chat App

Irl Nathan, sails cast series:

Sails Cast Presentations

Intro to Sails - presentation slides:

Presentation Slides

Intros on Json Web Tokens (JWT, pronounced JOT)

• http://angular-tips.com/blog/2014/05/json-web-tokens-introduction/
• https://auth0.com/blog/2014/01/07/angularjs-authentication-with-cookies-vs-token/
• http://angular-tips.com/blog/2014/05/json-web-tokens-examples/

Once you have internalized that information, then subscribing (following) to the Github repos for sails, waterline etc, joining the google group discussion, IRC channel, youtube video postings, and searching / asking questions on SOF usually resolves other points of uncertainty.

What I really wished I had most of all in retrospect (having just released a complex commercial application) was a comprehensive reference application to compare against with regards to some configuration / layout / and code aspects. The documentation and existing samples were particularly thin regarding productionising a deliverable.

[gihrig]

@arcseldon and @rattrayalex

Interesting and valid diversity of opinion. This shows the need for a production quality application and a comprehensive tutorial/documentation. Sails already has good start on documentation.

My thoughts on having the app first come from the feeling that given a well written app created by Sails core devs, I, and many others here could contribute meaningfully to a tutorial. But I have already failed at surmounting the learning curve to the point of creating a production quality app in the time I have available.

Requesting that the core devs create the example app to match the tutorial outline seems reasonable because they do this at Balderdash and are best qualified to meet @rattrayalex's concern over appropriate idioms of the framework, best practices, etc. Though this would demand well commented code, I think it's more reasonable to expect that from core devs than a well written tutorial.

An example app would certainly leave questions unanswered, and in fact, the questions are a critical piece to the learning puzzle. While core devs may not appreciate the subtleties of why they do things as they do, confused community members certainly will want to know why, and will ask.

I think the key to a successful learning/documentation project will be to understand the needs and who can answer them most efficiently. My feelings:

Creation of a production quality app - core devs
Creation of a comprehensive tutorial - 'writers' among the community
Needed improvements in the tutorial or app - users in the community
Rinse and repeat ;-)

In short, it's what 'community' brings to an open source project. @newz2000 made a great start, it's exciting to see the process unfolding for Sails.

[newz2000]

@gihrig by the way, it was mentioned that there is a project to create reference applications at https://github.com/sails101. I've downloaded some of them and looked them over at a glance. Each seem to focus on a single concept, which makes the code a little easier to read.

One problem with a reference application is that any application is going to have a combination of boilerplate code and non-boilerplate code. (or in the case of Sails, code may mean configuration)

It's very easy to miss an important change to one file that causes the application to not work. In those cases a better solution may be to see a sliding diff where you could watch all the changes unfold in a step by step manner. In a sense, this is kind of what a tutorial is.

The main take away point from that previous thread that is feeding into the issue I've created here is the goal to produce more intermediate and eventually advanced users. Code examples are targeted at intermediate and advanced users who are good at reading code. My hope is that we can create something that beginners can use to rise up to the level where example code is more useful.

[dancancro]

That sounds like how they did the Angular phonecat tutorial https://docs.angularjs.org/tutorial. It uses github. You get the code for the first step, read the guide for that step and follow along at home, then run a simple command to erase the code from that step no matter how much you messed it up and get you a clean set of files ready to go for the next step. That's the best way I've seen for doing this so far.

On Fri, Oct 24, 2014 at 8:48 PM, Matthew Nuzum notifications@github.com wrote:

@gihrig https://github.com/gihrig by the way, it was mentioned that there is a project to create reference applications at https://github.com/sails101. I've downloaded some of them and looked them over at a glance. The each seem to focus on a single concept, which makes the code a little easier to read.

One problem with a reference application is that any application is going to have a combination of boilerplate code and non-boilerplate code. (or in the case of Sails, code may mean configuration)

It's very easy to miss an important change to one file that causes the application to not work. In those cases a better solution may be to see a sliding diff where you could watch all the changes unfold in a step by step manner. In a sense, this is kind of what a tutorial is.

The main take away point from that previous thread that is feeding into the issue I've created here is the goal to produce more intermediate and eventually advanced users. Code examples are targeted at intermediate and advanced users who are good at reading code. My hope is that we can create something that beginners can use to rise up to the level where example code is more useful.

— Reply to this email directly or view it on GitHub https://github.com/balderdashy/sails-docs/issues/317#issuecomment-60432114 .

[gihrig]

@dancancro

The Angular phonecat tutorial presentation looks really good as a learning aid. It might not be hard to replicate for someone familiar with Angular. Even a Github repo with well co-ordinated commits for each step would do as a start. Still a production quality app would be required as the stating point.

[CWyrtzen]

Does this answer the question: http://irlnathan.github.io/sailscasts/ @irlnathan

[sailsbot]

Thanks for posting, @newz2000. I'm a repo bot-- nice to meet you!

It has been 30 days since there have been any updates or new comments on this page. If this issue has been resolved, feel free to disregard the rest of this message. On the other hand, if you are still waiting on a patch, please:

• review our contribution guide to make sure this submission meets our criteria (only verified bugs with documented features, please; no questions, commentary, or bug reports about undocumented features or unofficial plugins)
• create a new issue with the latest information, including updated version details with error messages, failing tests, and a link back to [the original issue](). This allows GitHub to automatically create a back-reference for future visitors arriving from search engines.

Thanks so much for your help!