Hi Terry, On Thu, July 6, 2006 1:25 pm, Terry Jones wrote:
> Thanks for all the very thoughtful replies to my long mail. I didn't mean > to whine about things and then just disappear back into the woodwork, I > just have to deal with various other things right now. I'm thinking about > what I wrote, the various replies, what might be effectively done, etc. > I > hope to be able to follow up again soon. I was one of the respondents to your much welcomed critique of Twisted documentation. And I would like to explore with you and others how to contribute toward improved Twisted documentation. Here's what I've done to date to make Twisted more available to the less technially astute: http://twisted.paisite.com. For reasons good and bad the Techno project is stalled, but it might be worth picking up again. 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? -- 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? -- What, if any, are the shortcomings of current documentation? -- 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. And looking at the source code I found numerous syntactical constructs that I simply couldn't penetrate. Now, granted, I had and still have limited experience with Linux, Python, and object architectures. But I was highly motivated to learn what I needed to know to use Twisted in my own projects. As I widened my studies and dug deeper I discovered yet another problem: Trying to discern a roadmap through the Twisted thickets was like following a well-paved road that turned into graded dirt then diverged into countless sandy paths that then faded into the desert. After several weeks pursuing the fractal-like tracks I, for one, felt stranded far from water and shade. What finally did me in was a severe electrical storm which blew out the machine on which I was doing my Twisted experimentation. Now I take full responsibility for my own intellectual and experiential shortcomings. Fact is, many good people put countless hours into creating the Twisted corpus of code and documentation. And I'm grateful for every minute of it. If they didn't reach me, it's not their problem. It's mine. But as your critique attests, backed by many others on the various lists, I'm not the only one looking enviously in on the party. I would have liked very much to have mastered, or at least sufficiently understood Twisted, to integrate it into my own projects, but there was simply not world enough nor time given the current state of docs. Now, encouraged by others seeking improved Twisted documentation, I'm delighted to offer again my limited skills toward that goal. But I need folks with knowledge beyond mine to lay out the path and point the way. All the best, Lloyd R. Prentice President Prentice Associates Incorported _______________________________________________ Twisted-web mailing list [email protected] http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-web
