[Twisted-Python] Call for documentation reviewers
mary-twisted at puzzling.org
Sun May 8 05:45:00 EDT 2005
They have been some people here pretty keen to have better
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
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.)
More information about the Twisted-Python