Hello, Wow!
You folks are amazing. I'm really stoked by the energies behind the last twenty-four hours of list traffic. Let me try to summarize/synthesize as best I can. Welcome all restatements, additions, and excisions. -- At the end of several insightful comments, Cary Dodt said: ...there's still lots of areas that *aren't* adequately documented by anyone's standards. There are areas not covered by examples, there are areas not covered by HOWTO's. The core is covered, but any new application worth writing probably uses stuff from the fringes. So our hypothetical new Twisted user starts out writing her new application, gets a handle on the core stuff, and then discovers those gaps in the fringes. That can be frustrating. Everyone uses a different part of the fringes, so the fringes need to be covered almost as well as the core. -- L. Daniel Burr and Valentino Volonghi generously offered help in resurrecting the Turkey series. -- Beau Hartshorne suggested: ...What do you think about task-oriented snippets and instructions, like a Twisted Cookbook? It might make writing and consuming the documentation a bit less daunting. Can anyone come up with say ten common questions that come up on the list? -- L. Daniel Burr responded to my suggestion of a road map: ...As for a roadmap, I think sticking with web-oriented topics is best for the vast majority of users. Most people are building web-apps today, so they represent a large audience. After perhaps adding some more details to your existing "Hello World" example, we could move on to "Talking to a database", then the usual "A web page that talks to a database". After that you could start talking about templating, etc. --Valentino the rolled up his sleeves with the following excellent suggestions for Turkey topics: ...The main question is for sure the following: - How can I authenticate with guard using a database? (talk about writing checkers) - How can I use an ORM inside Nevow? (talk about Axiom, twisted.enterprise.adbapi, sqlalchemy+sAsync or simpler transactionToThread) - How do I handle forms in Nevow? (talk about formal) - What's the preferred way to share global state in a Nevow application? (talk about passing something in the root page and having the root page to pass that over and over to all children) - How do I do nested sequences? (there's already an example, should be better documented) - Man I hate how nested data_* directives behave, what are they doing? (talk about IContainer) - What is a macro? (talk about one-time renderers) --glyph reminded us that our task could be of value to many people and covers substantial ground: ...It's (Twisted) generally useful in a huge variety of problem domains. Even if you're just doing IPC, not network IO, Twisted can help prevent deadlocks and generally make applications a lot more robust. The "specialist" label is an unnecessary compromise; if our documentation is crap for some of those domains, then let's just say *that*, and all work to improve it, rather than pretend that there is something wrong with the technology itself as an excuse. If we officially say "this is not a general-purpose tool", then pretty soon all the functionality it provides outside the "specialist" area we artificially create for it will atrophy and eventually be removed. --Beau Hartshorne elegantly refined Valentino's road-map suggestions: ...How about titles more like: - Authenticating Web Users - Using ORMs (Databases) - Parse and Validate a Form - Share Global State - Rendering Nested Sequences - Nested Data Directives - One-time Renderers - User Sessions - Virtual Host Setup With these suggestions I believe we're well on our way. Questions: --Does Beau's list cover the necessary and sufficient application issues, conceptual concepts, and code objects and components to bring a newbie to reasonable competency when it comes to building websites and applications in good Twisted form and style? --Is the list sequenced to build from least assumptions about prior knowledge to most? --Should we have an adventure dealing with site security and/or putting a Twisted site into production? --The Turkey adventures to date had more-or-less the following structure: - Short, runnable code example - Discussion of anticipated results - Discussion of how it works -- concepts, theory, references to Twisted docs and source - Conclusion Can this structure be improved? Seems to me that with another round or two of hammering on the road map we will be well on our way toward developing some real adventures. Hat's off to all... Lloyd _______________________________________________ Twisted-web mailing list [email protected] http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-web
