[Twisted-Python] Questions about adding documentation

Steve Steiner (listsin) listsin at integrateddevcorp.com
Fri Jul 31 16:04:18 EDT 2009


On Jul 31, 2009, at 3:37 PM, Ying Li wrote:

> 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

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




More information about the Twisted-Python mailing list