[Twisted-Python] Re: Docs for twisted?

[Ed Suominen]

The lack of detailed, current documentation for Twisted is an ongoing 
problem, especially given how revolutionary and difficult to understand 
its underlying programming concepts are.  Dave Cook's "just use it for 
months" comment is not at all off the mark, but it's a frustrating and 
unproductive way to learn.  It particularly annoys me that the code 
contains so few docstrings -- Python's especially useful and convenient 
way to document your code -- and there are so many nonsensical "cute" 
names like jelly, banana, etc.

Putting my money where my mouth is, I would be willing to contribute a 
few hundred bucks to getting some more docstrings in the code and, 
consequently, to a somewhat better lore-generated API specification.

One thought would be to run a "bounty" program using an 
actively-generated, hyperlinked web rendition of the latest Twisted SVN 
code.  For example, participant donors could mark defs, classes, or 
blocks of code to indicate where they're willing to "sponsor" 
docstrings, and they could also click on newly added docstrings in such 
"sponsored" code portions to indicate acceptance and make a bounty 
payment from their contribution to the fund or whatever to the person 
who wrote the docstring.  The proportion of docstring submissions 
accepted by a given donor could be a score that potential writers could 
look at when deciding whether to do the work or not.

Any thoughts on that idea?  Anyone willing to step up as a 
co-contributor to such an effort, both financially and with some Nevow 
coding?

---
Ed Suominen
Registered Patent Agent
Open-Source Software Author (yes, both...)
Web Site: http://www.eepatents.com