[Twisted-Python] Motivations of Twisted Developers & $200 Docstring Challenge

[Ed Suominen]

"James Schend" <blakeyrat at gmail.com> wrote:
> Look, all I want to be able to do is to write a program that can sit on a server for 10 years and run without me touching it.  My users won't necessarily be technical and (much more likely) the program won't necessarily be maintained, so it is important that the libraries used, if any, won't break my code with updates.
> 
> Maybe those are strange, unheard-of, constraints, but either way it looks like I have to write my own telnet server.  I'd rather not, and I'm sure you'd rather have me as a user, but that's just the way it is.

I'm an active user of Twisted, but even after several years, I'm still
not sure whether the Twisted developers really *want* you as a user or
not. I'm not saying that with any hostility; I'm actually a big fan of
Twisted and those behind it. They certainly have been very helpful to me
with my specific questions on IRC, and in that way it's one of the most
responsive and "live" F/OSS projects around. Frankly, I think the
Twisted developers understand Python and the theoretical underpinnings
of software engineering better than 90% of the people developing with
Python today.

On the other hand, though, much of the style of development that goes on
almost seems *intended* to turn off potential users, such as abandoning
subprojects mid-stream in favor of a Next Big Thing that remains a
moving and largely undocumented target for long periods of time, and
failing, for reasons incomprehensible to me, to simply write even 2-3
lines explanations of what their New and Improved code is actually
*doing* in the docstrings that Python so conveniently provides for that
purpose. Ironically, one of the latest examples of this is a document
extractor under development that is supposed to fix some alledgedly
grevious flaws in epydoc (undetected by this user, by the way) that
actually has very little source material to work with from the Twisted
code itself!

Another most unfortunate example is that the most powerful way to do
networking with Python is without a recommendable HTTP server. The
Twisted devs won't recommend twisted.web because it is "hopelessly
broken" yet they have nothing released to support it. Twisted web2
remains largely undocumented and the developers advised those using it
to do so at their own peril. Note to developers: serving HTTP is the
biggest single use-case for Python networking!

I've complained about these issues for a long time. Now I'm going to put
my money where my mouth is. I hereby commit to a two hundred dollar
($200) payment to Twisted, c/o the exarkun at divmod.com account listed
under the "Contributing" heading of http://twistedmatrix.com/trac/, in
exchange for one or more of the Twisted developers committing SVN/trunk
changes in the next two weeks that implement at least 100 meaningful
class or method docstrings in new or active portions of the Twisted API.
(I'd personally appreciate a focus on twisted.web2 as that's what I'm
spending my time on right now, but this challenge is open to any active
parts of the API.)

That works out to $2 per docstring, and those "in the know" should be
able to write them in just minutes apiece. Spend five hours writing all
of them (improving "your" parts of Twisted in the process) at 20
docstrings per hour and pocket $40/hr for your efforts. It sounds like a
pretty good deal to me, and hopefully to the Twisted devs as well.

If this challenge is accepted and it works out well, I might even do it
again -- I'm *that* interested in the ultimate success of this sometimes
wonderfully crazy library/framework/Integratotron*

Let me know.

Best regards,
Ed Suominen

* See Glyph's somewhat amusing and thought-provoking blog entry of March
15: http://glyf.livejournal.com/54500.html