On Aug 30, 4:32 pm, cd34 <[email protected]> wrote: > The documentation for almost every open source project leaves a lot to > be desired. Pylons is no different. Certain examples are well > documented, but some documentation is clearly written by a programmer > and is almost a dump of the API with a comment thrown in.
I agree with the first part, but rather than API I've found many docs in this world to be "chatty" docs with examples but no good comprehensive reference. Examples are OK as a supplement to API docs, but someone who is creating a novel web application is going to need to know how to do things in a way that they aren't done in an example, which means a full accounting of available tools including usage, argument/return types, etc. I.e. good API docs. For instance, the AuthKit documentation in the Pylons Book is almost purely by example. The SQLAlchemy backend isn't even introduced until the chapter after the "Authentication and Authorization" chapter, and it's done so in passing as part of a site example. Of course, plain API dumps aren't great, either. Generated API docs tend to suffer from both false positives (internal functions/classes, since Python lacks public/private keywords and many developers don't use leading underscores consistently) and false negatives (e.g. dictionary keys or configuration keys, which will be left out of generated docs that focus on functions/classes.) IMHO, a really good example of API docs in the OSS web world is jQuery. Even though it's a straight item-by-item API reference, it was obviously put together by humans as it divides things into use-based categories (traversal, manipulation, etc.), and includes non-function items such as string-based selectors. > You've got me, for better or worse, because of SQLAlchemy. All of the > other components are similar enough between the Python frameworks that > it is just a matter of syntax to switch from one to the other. > > How will Pylons differentiate itself from the rest? Answer that, and > you'll be at the top of the heap. SQLAlchemy+Mako drew me as well. They're good, but they can be & are incorporated into other projects. Really, a programmer who's beyond the tutorial stage can put together libraries or frameworks how they want or roll their own. But rolling your own integration and deployment can cause problems with maintainability and transferability (i.e. getting someone else to work on it later). I think that's why "convention over configuration" is a powerful concept. Conventions mean that someone else can maintain your code. I think a framework can succeed based on being able to more-or-less guarantee that useful items will be present (interfaces, environ keys, whatever) in a normal deployment of that framework, in a way that nevertheless does not restrict what the programmer wants to do. So, what is the Pylons "promise"? That would be a good focus for docs + promos. Some of the "conventions" of pylons are actually created by paster create -t pylons, rather than, say, the implementation of the PylonsApp WSGI app, so it would also be useful to distinguish between the two. --~--~---------~--~----~------------~-------~--~----~ 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 -~----------~----~----~----~------~----~------~--~---
