Now merged and available at: http://docs.pylonsproject.org/projects/pyramid/en/master/
If anybody has some time and is willing to go through the Quick Tour: http://docs.pylonsproject.org/projects/pyramid/en/master/quick_tour.html ..I'd appreciate it. If you find something wrong, email me directly or file a ticket here: https://github.com/Pylons/pyramid/issues ...assigned to me with a "docs" label. I'd like to start promoting this Quick Tour later this week. --Paul On Aug 13, 2013, at 7:59 AM, Paul Everitt <[email protected]> wrote: > > tl;dr New "Quick Tour" docs in the official docs ("The Book") as part of > effort to appeal to "Getting Started" audience > > Hi everybody. Last year Chris raised some funds for a documentation effort. > After some false starts, we have a `docs.gettingstarted` branch ready to > merge today as the completion of that effort. This email talks about what was > done and what might be done next. > > The existing docs are awesome. They are very detailed, always up-to-date, and > cover nearly everything. The feeling was, they cover too much and are > intimidating to people just getting started. This branch introduces the > results of a lot of thinking: > > - We identified an "Evaluator" target audience...non-advanced Python > developers or advanced Python developer who are in a hurry > > - Cover "a little about a lot", meaning clearly identify major features, give > each a light treatment, then link to the big writeup in the existing docs > > - As a way to give more visibility to Python 3, have this document (like my > PyCon tutorial) presume Python 3.3 but tolerate Python 2.7 > > In doing this new Quick Start, I found some other stuff to do: > > * I renamed almost all occurrences of "Pyramid web application development" > -> "Pyramid web framework" > > * I changed all the inline code snippets to point at working code, using > literalinclude's :start-after: and :end-before: to point at the relevant lines > > * This means the snippets are executable and can be tested more easily to see > if they break in future releases > > * I made a big push to use Intersphinx so that our inter-docs references > survive changes in the future, including going to Deform, Beaker, etc. and > putting in a label that I could point to > > * Blaise and I did mockups for a marketing-oriented site that focuses on > Pyramid evaluators (long project) > > * I took the "Getting Started" section from the Pylons/pylonsrtd Pyramid page > at: > > http://docs.pylonsproject.org/en/latest/docs/pyramid.html > > ...updated it, copied it into "The Book", and synchronized the contents > (more below) > > * I moved some non-book stuff out of "The Book" and moved over to the > pylonsrtd Pyramid page > > * I have some other changes to pylonsrtd that I can push out once this > Pylons/pyramid docs branch is merged > > Thanks to Tshepang and Steve Piercy for helping steer me on the writing of > these 20 printed pages. What's next? Way more than can possibly be done. > > - Merge the docs.gettingstarted branch to master > > - Push pylonsrtd changes > > - Change license to CC BY-SA > > - Update the install chapter > > - Close some docs bugs (64 open docs tickets) > > - Make a pointer to the Pylons Pyramid page, from "The Book" > > - I really ought to write Quick Tour sections for Contexts and Root Factory, > Authorization, and Authentication > > - Move 3 of the 4 "The Book" tutorials to pyramid_tutorials > > - Start rewriting the one left behind, making it into the official tutorial > > --Paul -- You received this message because you are subscribed to the Google Groups "pylons-discuss" group. To unsubscribe from this group and stop receiving emails from it, send an email to [email protected]. To post to this group, send email to [email protected]. Visit this group at http://groups.google.com/group/pylons-discuss. For more options, visit https://groups.google.com/groups/opt_out.
