[Twisted-Python] User notes for documentation.

[Andrew Bennetts]

On Sun, Jul 06, 2003 at 12:42:51PM +1000, Rene Dudfield wrote:
[...]
> 
> Add a bug report link/form at the bottom of each section of 
> documentation.  This can include feedback on the docs, and bug reports.  
> Often times when people are looking at docs, it is because they have a 
> problem they want a fix for.  So it makes sense to ask for bug reports 
> in the docs.  Like the feed back suggestion of Glyphs, automatically 
> include a way to track down which document the report was made from.

I agree that something like this should be added to the documentation
template.

> Also other users can post notes about wrong comments which remain.

GAH!

So rather than just getting the docs fixed, you'd get band-aids being put on
band-aids, because the first band-aid was broken!  This is why I, as a
reader, don't like user comment systems: as you read a document's comments,
you have to keep mentally shifting your view of what you've just been told,
because the comments will contradict the docs, and each other, and you have
to keep mentally backtracking to figure it all out.  

We should be striving for the docs which are correct, and make sense on
first reading, rather than requiring the reader to continually re-read
paragraphs because a comment added "but that only applies when using Foo".  

Perhaps the strongest argument I can make against this is the Zope 2 docs --
user comments have not made them magically useful.  On the contrary, I've
found them to be neglected and incomplete, despite the efforts of the large
Zope community.

You can't fix docs by people scattering little two-liners here and there
saying "actually, that didn't work for me."  

Let people post comments to a real mailing-list.

> Another good addition to the docs would be a listing of significant api 
> changes.  If it's not in there allready somewhere.  eg differences 
> between 1.02 and 1.03, 1.03- 1.04, 1.05-1.06, etc.

That's what the ChangeLog file in the distribution is for, although it's not
readily accessible as a link off the website.  To a lesser extent the
release announcements do this as well; they usually mention the major new
features.  We are generally very good at being backwards-compatible, so
perhaps the best source of details about the changes are any
DeprecationWarnings you get running your code with a new release ;)

-Andrew.