Thank you for doing all the work. This will make it easier for
me to guide newbies through an introduction to Pyramid at user
group meetings.
Speaking of which, if you are in the San Francisco Bay Area, I
will be attending the following meetups to test drive the new
documentation that Paul wrote, as well as hacking on docs.
Please introduce yourself and say howdy!
Tue, Aug 13, 6:30 - 9:00 PM, Mountain View, CA
http://www.meetup.com/PyLadiesSF/events/126437852/
Wed, Aug 14, 6:00 - 9:30 PM, San Francisco, CA
http://www.meetup.com/sfpython/events/133797252/
--steve
On 8/13/13 at 7:59 AM, [email protected] (Paul Everitt) pronounced:
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
------------------------
Steve Piercy, Soquel, CA
--
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.
