On Mon, Feb 6, 2012 at 12:02 PM, Mike Orr <[email protected]> wrote:
> +1 for splitting the manual into simple and advanced, however that's > defined. Simple = normal application usage based on the built-in > scaffolds. This would include both Chameleon and Mako, and maybe > traversal. Advanced = optional customizations such as new renderers or > ZCA. > > On the topic of parallel docs, here's what I would do, adopt or reject as you see fit: - The easy book/docs focusses on Pyramid in 'Pylons/Django' style, which is how most people are going to want to be introduced. It doesn't dwell on interfaces, adapters, zcml, views as classes, overriding resources through zcml, etc. Readers of the easy book just get up and running with Pyramid as fast as possible. The acid test of this stream is "how good and quick was your hit the ground running experience?" This book impresses all those people who like to write "web framework shootouts" after only using the framework for a day ( barf! ) - The advanced book goes Under The Hood. It explains what's happening and how it all is lashed together as a component architecture system, and all the myraid places you can hook into or override this system. It covers views as adapters, registering them by interfaces, zcml_pyramid, using the resource system, more on custom factories, writing your traverser, etc. The acid test on this stream is "could you replace any component in the pyramid system with a version of your own after reading all this" I would personally make them connected. So each page in the easy book has a link to "under the hood", where we find out how pyramid actually accomplishes this and where you could tinker with how it's done. And the advanced section heavily points at good further reading. ie, it doesn't have to be the definitive guide to using the ZCA, there already is a good one, so it being advanced, it can be fairly terse on what you use a zca interface for and point somewhere else for more details. my two cents canadian iain - the advanced book digs under the hood, -- You received this message because you are subscribed to the Google Groups "pylons-discuss" group. To post to this group, send email to [email protected]. To unsubscribe from this group, send email to [email protected]. For more options, visit this group at http://groups.google.com/group/pylons-discuss?hl=en.
