Next stop the world (Re: [Twisted-Python] Beginners Guide to Twisted Anywhere?)
mary-twisted at puzzling.org
Thu Aug 5 23:27:42 EDT 2004
On Thu, Aug 05, 2004, Cory Dodt wrote:
> Great notes! The extra detail on Deferred and Application should be
> especially helpful. Can we get edit this a bit and get it into the
> official docs? (I know.. open a doc bug.)
Mike, thanks very much for writing this. It would be great to be able to
incorporate it into the actual tutorial. I'm happy to do the work of
incorporating it (I'll even file the bug against myself), but you would
need to agree to this:
... all your contributions (including those initial patches you send
to the mailing list) will have to be copyright consigned to the
project leader, Glyph. The reason for this is flexibility in
changing the license.
I'll likely contact you off-list if I don't hear from you.
I've been paying attention to complaints about the tutorial and do
intend to work on it. In fact, I'm unemployed (by choice) for at least
the next four months and hope to do extensive work on Twisted docs
(among other writing projects).
However, (once again), people could help out by understanding the
1. The Twisted docs are not perfect, complete, or, in fact, adequate.
The project would like them to be better. We're not deliberately
choosing the docs to be the way they are.
Your criticisms are most likely valid. Your ideas for additions are
most likely excellent.
In particular, the tutorial as it stands was designed to be presented
by a Twisted expert and listened to. It wasn't designed to be read. It
*severely* needs additions to deal with the change in media.
2. The best way to improve the Twisted docs is to do some writing
yourself and contribute it to the project. Send it to me via email or
via the bugtracker ( http://twistedmatrix.com/bugs/ , assign to
"hypatia" ). I am willing to edit it, format it, extend it and add it
to SVN. In fact, I'd be so pleased this would probably happen within a
It would also be great to have more regular docs writers (since I don't
qualify for this description) committing to SVN themselves :)
3. In this case, we do have a "someone" who has some sense of
responsibility towards the docs, and that someone is me. If you don't
want to contribute yourself, help me improve the docs by filing bugs.
I'd like people to take note of #1 in particular because a lot of this
week's threads have focussed on solving the doc inadequacies by having
external documentation. Improving the existing docs is another
(complementary) path forward.
More information about the Twisted-Python