Next stop the world (Re: [Twisted-Python] Beginners Guide to Twisted Anywhere?)

[Mary Gardiner]

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.)

Yep :)

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.

    http://twistedmatrix.com/developers/contributing

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
following:

 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
 week.

 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.

-Mary