[Twisted-Python] User notes for documentation.

[Glyph Lefkowitz]

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 
> reading

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 
and otherwise.

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 
primary responsibility.