On Jul 31, 2009, at 3:37 PM, Ying Li wrote:
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
That is one of my pet peeves about project documents of any type. Tutorials, and examples especially. There's nothing more frustrating than getting 1/2 way through a tutorial, only to realize that the rest of it is just not going to work with the current version and that all that effort was wasted because that's not how it's done any more. If it's not dated, and perhaps tagged with the first version with which it was released, and the most recent version at which it was modified, it's impossible to figure out what's current, relevent, and likely to actually work with the current release. S