Make Pyramid Blogr the new official tutorial for pyramid

[ergo]

Hi,

I would like to suggest a change to pyramid documentation, I've create a tutorial to guide people on how to write a small pyramid application from start to finish, covering various aspects of development.

You can find the tutorial here:
http://docs.pylonsproject.org/projects/pyramid-blogr/en/latest/

Over last years I received a lot of positive feedback about the tutorial (Its been used as a base for other tutorials and workshops over the globe), over email and in person when doing pyramid workshops at local python meetings and on polish pycon.

The tutorial is currently updated for latest 1.7 scaffolds so I was thinking it would be a good idea to make it the new introductory material for pyramid.
It tries to mirror my personal experience when migrating from php to python using pylons + pylonsbook, I got quite good results with it on training sessions I did in the past.

[stevepiercy]

My greatest concern about accepting another tutorial into the core documentation is maintenance. We've learned from the Pyramid Community Cookbook that unmaintained documentation becomes a dusty relic over time. We've also learned that updating step-wise tutorials requires significant labor.

I see benefit from including another perspective of how to build a Pyramid app. Everyone has different teaching and learning styles, and more options might help folks find what works for them.

I've run through pyramid-blogr a couple of times, and I think it's a good tutorial without any deal breakers.

However, there are some things also in the works for Pyramid 1.8, namely issue #2384, which would impact pyramid_blogr as well as all current tutorials. Maybe get Pyramid 1.8 done, then add this to Pyramid 1.8.1?

[ergo]

Sure, that seems like a reasonable option, when #2384 lands i can begin work on that. Everything else is 1.7+ compatible so its just a matter of updating the first step that creates new project probably.

[mmerickel]

Personally I'm not sure adding yet another tutorial to the docs is a good idea. That's partially because I put many many hours into the revamp of the tutorial for 1.7 and think it's not too bad, but it's also because the current traversal-based tutorial is also very out of date and we simply don't have anyone who wants to maintain it. This makes me very very wary of adding yet another tutorial which puts even more of the maintenance burden on core.

[ergo]

I guess we can leave things as they are, so far I maintain the tutorial and its 1.7 version ready, maybe it can just be mentioned in the docs somewhere as an alternative.

[mmerickel]

The main difference (to me) between pyramid-blogr and the wiki / wiki2 tutorials is that I, and the other core developers, make sure they actually still work before major releases. This warrants some sort of asterisk / credibility in my mind with the caveat that if you're committing to maintain pyramid-blogr in a similar fashion then I agree we should give it the same level of credibility.

We might consider pulling wiki, wiki2 and mod-wsgi out of the core documentation which would put them on a more equal footing with pyramid-blogr. They would then all be linked from http://docs.pylonsproject.org/projects/pyramid-tutorials/en/latest/index.html#pyramid-tutorials. From there we can consider how to best order them, etc, likely by adding an official section, and another for the third party stuff (blog posts, conference presentations, cookbook entries, etc).