Improve SQLAlchemy tutorial (wiki2) according to paulo docs punchlist

[mcdonc]

Keeping track of sqlalchemy tutorial new user confusion issues at https://docs.google.com/document/d/1u127sxnxBmQ7viOkjNeTP-yTlGs_0AmFUH8CKuGXLpc/edit?pli=1

[ghost]

This doc appears to be inaccessible without signing in to google.

[mcdonc]

This is the text of the document. The google docs version contains comments by @ppaez which are not included here.

Display VISIBLE "Previous" and "Next" buttons in all the pages, keyword here is VISIBLE :)

The documentation says to run 
$ bin/pcreate -s alchemy tutorial

After doing so i get the foollowing message
    Welcome to Pyramid.  Sorry for the convenience.
    Please run the "populate_tutorial" script to set up the SQL database after
    installing (but before starting) the application.

which in my case i it looks like an error, my suggestion is to word the message better

When running populate_tutorial development.ini , i got an IOError, due to the fact that i wasn't on the tutorial directory.  

Coming from django, i find the act of importing all the sqlalchemy stuff in the models.py and any other file that defines models, very repetitive 

Specify whether the commands run are specific to the tutorial ?? eg. populate_tutorial development.ini

When on the "Adding dependencies page" please specify which dependency i am adding, rather than having me copy the entire file and replace it

Specify the user that he/she needs to create the templates 
http://docs.pylonsproject.org/projects/pyramid/en/latest/tutorials/wiki2/definingviews.html#the-view-pt-template

*Comment* Why have the user remove all the generated stuff from the tutorial ( models, views, etc )

*Very important* tell the user to run the command to start application BEFORE doing this
http://docs.pylonsproject.org/projects/pyramid/en/latest/tutorials/wiki2/definingviews.html#viewing-the-application-in-a-browser
because the tutorial assumes that the user ( first time user ) already knows which command to run to start application

When changing the http://docs.pylonsproject.org/projects/pyramid/en/latest/tutorials/wiki2/authorization.html#configuring-an-authorization-policy
we need to specify that we have to add the configuration to main() and replace 

config = Configurator(settings=settings)

with 

config = Configurator(settings=settings,
                          root_factory='tutorial.models.RootFactory')

in my case i got confused as to where in the main() function i was supposed to add te security config

In http://docs.pylonsproject.org/projects/pyramid/en/latest/tutorials/wiki2/authorization.html#changing-existing-views, 
instead of saying..

We’ll add something like this to each view body:

from pyramid.security import authenticated_userid
logged_in = authenticated_userid(request)

We need to separate the lines so that the user does not add the import statement to every view
in the sqlalchemy tutorial, the part that says to “add this code to all views”

Grammatical Error ( Location )
    Suggested fix
- within the code which does
+ within the code that does

Grammatical Error ( Location )
    Suggested fix
- allows you to compose applications
+ allows you to combine applications


SQL Alchemy tutorial: Explain the root factory - another example that is not applied to security.

[mmerickel]

I think the wiki2 tutorial updates in #2024 have drastically improved on this and addressed almost all of the comments.