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.
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.
-- 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.
-- What, if any, are the shortcomings of current documentation?
Maybe it's too concise. Every word in the current documentation must be
carefully
read because it's meaning is incredibly important to actually understand the
text.
Some things are implicit in the meaning given to that word and are never
explained.
-- Is it possible for us, given all constraints, to better organize our
efforts toward improved documentation and, if so, how?
Here's my personal experience with Twisted:
I spent considerable time last year studying Twisted documentation. I was
encouraged by an assertion that the Twisted developers were hoping for
widest possible adoption of the Twisted framework. But as I moved further
into the docs I discovered that much of it was written in a highly
specialized argot -- jargon or precise technical language I'll let someone
else decide. But, with full acknowledgement of my own inexperience and
shortcomings, much of it was completely incomprehensible to me.
Yes, that's what I mean by 'concise'.
And looking at the source code I found numerous syntactical constructs
that I simply couldn't penetrate.
This is another 'defect'. Twisted developers are extremely capable in python and
they tend to use the language as much as possible. Of course this requires the
same knowledge from the reader.
In my opinion this is a good thing overall, the only problem is that sometimes
docstrings are missing and this makes reading code harder than it could be.
HTH :)
_______________________________________________
Twisted-web mailing list
[email protected]
http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-web
