[Twisted-web] Re: Thoughts on documentation, wading into Twisted, Nevow, etc.

[lloyd at paisite.com]

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