On Fri, 07 Jul 2006 07:10:51 -0500, Valentino Volonghi aka Dialtone
<[EMAIL PROTECTED]> wrote:
On Thu, 6 Jul 2006 15:34:16 -0400 (EDT), [EMAIL PROTECTED] wrote:
It seems to me that one of the first questions in software documentation
is: "Who are we writing for?"
Given that, the next question is: "Who much or how little can we assume
that our consumers already know?"
Several questions, then, for the Twisted community:
-- Are we satisfied with the current level of adoption of Twisted in new
projects; e.g. do we want to remain a relatively small commmunity of
elite
developers and user or would we like to attract and build a broader
community?
I don't think we can be satisfied but unfortunately IMHO the real
problem with
twisted is not twisted itself but the big shift in the way you should
think
that drives away most people. I know many intelligent and very capable
programmers that do understand twisted (or are able to) but they do not
intend
to learn it because they feel it's hard while threading isn't as hard as
we
picture it. Having more and better documentation will help, many graphs
about
how things actually work _DO_ help but you can do only so much to attract
new people.
I think that worrying about attracting an audience that prefers to use the
thread-based approach is doomed to failure, in the same way that inviting
a conservative to adopt liberal ideals is doomed to failure.
One of the most needed things is to collect a page inside twisted
documentation
about the many reasons why threading is harder than the twisted approach
and
why. Currently there are many documents that try to explain this at
various levels
but a single, clear and simple one is missing. Even writing two
alternatives
using the two different models could probably help.
I don't think this would help much either, in that people who like to
use threads most definitely do *not* see them as being harder to use
than the twisted approach; on the contrary, they find threads to be far
more natural to their way of thinking, and most of them have never run
into the kinds of serious problems that threading can introduce. I
sincerely believe that until a person actually encounters a serious
thread-related problem, they cannot be convinced to adopt anything that
does what twisted does.
-- Is the corpus of Twisted documentation as it stands sufficiently
serving the needs of the community or is it holding back our efforts
toward longer-term goals?
I don't think I can answer this question. When I first learnt twisted I
used
the documentation and found it pretty good.
I have to agree here. I have used twisted since the 0.9 days, and I have
always found the documentation to be perfectly adequate. Honestly, while
I recognize that the vast majority of interested parties find the docs to
be incomplete or confusing, I have never had the problem, and so I am
struggling somewhat in understanding how to solve it.
Note that I am the furthest thing from an expert programmer, in any field,
so I don't think the "only really smart people can understand twisted"
argument doesn't hold in my case. Quite the opposite, actually; I use
twisted because it solves a lot of the hard problems for me, and I can
just concentrate on my application.
Perhaps the problem is that the twisted docs primarily teach the theory
of operation (Deferreds, Protocols, etc.). For someone like myself, the
theory of operation is exactly what I want to know. For others, I suspect
there is more value in documentation that covers things of a very specific
nature, such as "how to build a web application that talks to a database",
or "how to build a DNS server", or other such use-case-oriented fare.
If so, then the real problem is that using twisted requires you to learn
the underlying structure (Deferreds, Protocols, etc) before you can get
started on your application. There is a movement these days in many
projects to get the user up and running without any prior understanding,
the thinking being that they will pick up the details later, as needed.
Personally, my brain doesn't work that way, but I know many people who
cannot tolerate my approach, and find it unbearably slow.
So, maybe a "Build a real, working, application in 15 minutes" is the
kind of fare needed to make twisted more palatable to the audience that
is currently being frustrated in achieving twisted zen.
L. Daniel Burr
_______________________________________________
Twisted-web mailing list
[email protected]
http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-web
