On Sep 12, 2010, at 4:24 AM, Mike Orr wrote:
> I've got a first draft of the Pylons 2 Users Guide done. The "hello
> world" page is the only page that's completed; it goes through
> installing a default application and looking through the application
> code. I haven't gone through the Pylons code or BFG code or BFG manual
> yet; I just went with "it must be so in order for the application code
> to work", based on an earlier email exchange with Ben about the
> application structure. The emails are also included for reference on a
> separate page.
Mike, this is a great first step! I think your "hello, world" in Pylons 2
should probably be adapted into a "Learning Pylons 2 for the Pylons 1 User"
type document. As it does a great job explaining differences in terminology,
where things come from (which is good for more advanced users, but maybe can be
excluded for someone just wanting to know how to do things the new way), and
some of the advantages of the new setup.
For the general documentation, here are the directions Chris and I were
thinking would be a big priority:
- Integrated documentation
This means that *everything* one needs to write and use Pylons 2 will
be in a single spot. This will involve documenting everything that we expect a
user to use, in the main Pylons docs. All the configuration options and how
sessions work (from Beaker), all the methods they would want to use of the
Request and Response object (from Pylons, BFG, and WebOb), all the docs on how
to register handlers, views, etc. (from BFG/Pylons), how to test an application
and the methods/object docs, and probably all the important bits someone will
use in Mako templates.
- Avoid mentioning what package provides what bit for the most part
This helps make the entire framework "feel" like an integrated whole.
And the majority of the time, no user really cares that the Request/Response
are WebOb subclasses, that the Pylons Configurator is a BFG subclass, that the
events they imported from Pylons are shadow points for BFG ones, etc. Maybe in
an Advanced chapter, where the components are dived into in detail, then the
background of where these things originate will be mentioned. For the new and
average user though, they just make the docs longer, and add unnecessary
information that makes it feel more hacky. (I know that right now the main
reason all the origins are mentioned is mainly because Pylons avoids
re-documenting them, which will no longer be the case.)
- Document Imperative
Only the pure Python configuration style will be documented throughout
the docs. Since we do want to have a single set of docs for *everything* and
some use cases might have people reaching for ZCML, we'll also retain the ZCML
configuration docs in a single chapter under an Advanced Pylons section. This
also highlights Pylons focus on pure Python configuration.
The package list you note there has me thinking that maybe we can drop
decorator, FormEncode, Routes, and WebHelpers from the Pylons dependencies.
This means that the things using it in the Pylons code-base will need to be
wrapped in try/except imports so that everything still works for legacy apps
with Pylons 2.
Cheers,
Ben
--
You received this message because you are subscribed to the Google Groups
"pylons-devel" group.
To post to this group, send email to pylons-de...@googlegroups.com.
To unsubscribe from this group, send email to
pylons-devel+unsubscr...@googlegroups.com.
For more options, visit this group at
http://groups.google.com/group/pylons-devel?hl=en.
