On Fri, Jul 31, 2009 at 10:19 AM, Santiago Aguiar<santiago.aguiar@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.)