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.
