[Twisted-Python] User notes for documentation.
glyph at twistedmatrix.com
Fri Jul 4 23:55:39 EDT 2003
On Friday, July 4, 2003, at 10:58 AM, Rene Dudfield wrote:
> A user notes system has these advantages:
These are disadvantages.
> - not having to bother people to post notes
This means that the development team remains unaware of bugs, as the
user community just works around them rather than helping to fix them.
> - being easier for people to add a note about something as they are
This ease of posting comments and lack of editorial review means that
half of the comments will be badly written and the other half will
simply be wrong.
I am strongly opposed to having user-comments on the documentation
because it encourages half-assed fixes to problems, both documentation
However, a snippet at the bottom of each page that said "Is this
documentation frustratingly incomplete or incorrect? Please send
feedback to twisted-python at twistedmatrix.com" followed by a suitably
munged mailto: hyperlink that will put some information about which
page is being referred to in the topic of the message.
Also if someone wants to take over as the documentation editor, I will
gladly cede decisions like this one to them. The biggest reason that
we don't have very good documentation is that nobody makes it their
More information about the Twisted-Python