[Twisted-Python] Questions about adding documentation

[Santiago Aguiar]

Hi Jessica!

I'm quite a newbie at twisted yet, and a newcomer to the project, so I 
do think that twisted documentation is one of it's more problematic areas!.

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).

I understand that *rewriting* outdated doc is a major task, that's why I 
just suggest deleting it ;) (maybe in a new Revised Twiste Doc section 
of the web site or the like), then it probably would be clearer where to 
start and what needs most work.

It could also be a good idea to try to make it more wiki-like at the 
beginning; I think there's quite a lot of people that would like to 
contribute with this, but having different documents/styles for 
different areas of the doc is not good, a wiki like doc might allow some 
people to work on giving a more cohesive look to the whole doc, and 
others to add the meat and bones, provide examples, etc, while allowing 
everyone to review it easily. Thinking about it, of course a doc on SVN 
would help in the same way ;).

Truth is that I really don't know which are twisted best practices at 
the time (what I do works, but I don't know if it's the best way to do 
it), and checking outdated doc just confuses things even more... better 
no doc at all.

I stop my suggestions here before someone yells me 'then do it!' :).

--
Santiago