On Wed, Feb 8, 2012 at 9:56 AM, Chris McDonough <[email protected]> wrote: > Pyramid's use of a ZCA registry is still an internal implementation > detail, and as such isn't really intentionally exposed to the outside > world. It won't make much sense for the docs to explain how Pyramid > works in terms of ZCA vocabulary such as "adaptation", or even link > heavily to things that explain what adaptation, etc is. Instead, > explanations of framework hooks and such should just tell them which > Configurator methods to call, just as the docs do now. Theoretically, > Pyramid may disuse the ZCA in a future major release (although it's > highly unlikely). > > ZCML is purely an add-on package via pyramid_zcml, with its own docs. > The core Pyramid docs will not cover it, although they might mention it > in passing.
It sounds like there's actually a third level, "Framework Developer / Internals Hacker". We've acknowledged that there would be such people, but we haven't given much thought to what kind of reference they might want. Of course we can't undertake to write anything like that now. But we can define the category and its scope, and make a place to dump unfinished notes on the subject, and transfer to it any existing doc sections that are at this level. It could go into the Cookbook as long as it's an obviously separate section. Or we could make a clone of the Cookbook for it. There are three particular advantages to having a level of "Framework Developer Docs", even if it never gets beyond the stage of a collection of notes. (1) It would reinforce Pyramid's reputation as a solid base for building higher-level frameworks. (2) It would give greater transparency to the internals, which would both satisfy hackers (who would read them) and reassure hacker-wannabes (who may read them someday, but are glad they exist now). That is essentially what the mass of Linux kernel docs and related HOWTOs have done. (3) It would give a place for super-advanced stuff so it isn't cluttering up the everyday documentation. -- Mike Orr <[email protected]> -- 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.
