[Twisted-Python] Questions about adding documentation
santiago.aguiar at gmail.com
Fri Jul 31 10:19:42 EDT 2009
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!' :).
More information about the Twisted-Python