[Twisted-Python] Questions about adding documentation

[Ying Li]

On Fri, Jul 31, 2009 at 10:19 AM, Santiago
Aguiar<santiago.aguiar at gmail.com> wrote:
> My suggestion would be that more than *adding* documentation, I would
> suggest to first search-and-destroy deprecated documentation. For me,
> one of the most frustrating parts of using twisted was reading through
> the twisted core doc, trying to do things and failing, and then
> accessing #twisted and get people tell me thinks like 'oh,
> tap/tac/tml/mktap are no longer used', or things like that (I don't yet
> know which ones are supposed to be used and which don't).


Something that I find irritating about a lot of documentation that I
read is that it is not dated.  All the twisted docs are labeled with a
version (currently 8.2.0) but this is meaningless to me.  I think a
big improvement would be putting in a small bit of context around the
documentation , such as:

* when the howto/tutorial was last updated
* what version (of deferreds/imap/whatever the howto/tutorial is
about) the howto/tutorial was written for

What would be even more useful, although it would also be a lot more
work, is to perhaps link to a diff between the code as it is now and
as it was when the tutorial was written.  Or just a changelog.

Also, I oppose deleting outdated documentation outright, as I think
limited information is better than none.  However, I think it should
be clearly marked as such, so readers understand that the doc may not
give them correct instructions.

(This does not apply to the API docs as since the API docs are
automatically generated, they should always current given the Twisted
coding standards.)