[Twisted-Python] Call for documentation reviewers

[Mary Gardiner]

Hey,

They have been some people here pretty keen to have better
documentation.

One concrete thing you could do right now to help that take place is to
review existing documentation for me. Steps:

 1. Write a brief description of your general Twisted user profile (how
    much do you know about Twisted? what have you used it for?) Note I
    don't care what this profile is exactly, it can range from "novice
    programmer" to "author of reactor framework."

 2. Find an existing howto or document.

 3. Read through it.
    3a. Note any and all points where you are completely lost.
    3b. Note any and all points where you think something could be
        clearer.
    3c. Run the examples. Do they work? Do they make sense? What lines
        of code don't you understand?

 4. Having developed a probably extensive list of criticisms, file a bug
    against the documenation at http://twistedmatrix.com/bugs/ , put in your
    user profile and all your criticisms, and assign it to "hypatia".

 5. If at any stage you are inspired to write additions to the document
    you are reviewing, also attach them to the bug.

I will really really really try to make an effort to improve documents
based on reviews as outlined above. If you file one and I don't, poke me
with a stick. Participatory criticisms like this are very constructive
compared to "I wish someone would do something" level criticisms,
especially since Twisted is an almost entirely volunteer effort.
Volunteering yourself is so much more effective than volunteering other
people :) (Thanks to the people who have already filed docs bugs coming
out of this discussion.)

-Mary