-
Notifications
You must be signed in to change notification settings - Fork 878
Documentation Roadmap
This page discusses planned and potential revisions to the Pyramid documentation. (Updated: February 2012)
- Pyramid docs
- Pylons Project docs (top-level switchboard page)
The Pylons Project has raised $5000 to fund an overhaul of the manual. The general plan is to shrink the manual's size and make it more user-friendly. The most advanced-level content will be moved to another manual or documents. A first cut at the types of changes we'd like to make are in DocumentationOverhaul.
A three-level structure of a Users Manual (everyday usage using Pyramids built-in scaffolds), an Advanced manual (more esoteric customizations you can make), and a Framework Developer's manual (super-advanced material for those writing higher-level frameworks or who want to learn about Pyramid's internals).
If you have a short FAQ answer or a HOWTO, put it in the Cookbook. Fork the Cookbook on Github, make your changes, and submit a pull request. See the Contributing page re copyright and license. All Cookbook material will be considered for incorporation into the official docs at a later date, if it's sufficiently relevant and correct.
If you have an external article you'd like to incorporate into the Pyramid Cookbook and you don't have time to do it now, or if you have an idea for one but insufficient time or expertise to write it, list it in the TODO section of the Pyramid Cookbook.
If you have a hands-on tutorial (generally, a step-by-step guide for building an application), put it in the Pyramid Tutorials.
If you have a piece that's neither a HOWTO or a tutorial, for instance how your organization is using Pyramid, put it in the Cookbook somewhere (make a new section if none of the existing ones are appropriate). Or write up an external blog post and put a link to it in the Cookbook.
Users: what would you like to see in the Pyramid documentation? List short things here. For long things, create a separate wiki page and link it here.
A central list of Pyramid extensions. Include a short description, and mention how well it's supported or widely used.
A central list of third party scaffolds for Pyramid. Include description of components (SQLAlchemy, Mako etc) and link to depositories.