[Twisted-Python] The problem with Twisted...

[Philippe Lafoucrière]

On Thu, 2003-06-05 at 14:45, jml at ids.org.au wrote:
> ... is that we have no word for "entrepreneur".

Especially the website which seems really designed by and for
developpers (is it bad ?).

> Firstly, his biggest concern was documentation. He said that he doesn't want
> to trawl through Twisted's source code to figure things out. These days, (most
> of the time) you don't have to do that, but occasionally you do. Of course,
> our code is generally quite readable (except for the odd module here and
> there).
> 
> Suggestions: 
> * API docs
>     Ask ten Java developers what they like most about Java, and nine will say
>     "the API docs". I humbly suggest that we should get better at writing
>     these.

I'am quite happy with the API but some method & params really need more
doc. 

> * Howtos
>     I remain somewhat unconvinced that the best way to write a book is to
>     present a series of HOWTOs. But then, I also reckon that most of what we
>     call HOWTOs, aren't.

I think howtos have to be reorganized. It's pretty hard to get started
with twisted. Moreover, I'am trying to make an application with woven,
and have difficulties with documentation on it. Maybe we need more
exemples.


> Secondly, he couldn't find any information on the twistedmatrix.com website
> that said "Managers, this is why you should use Twisted". I hate writing that
> sort of thing, but I imagine it needs to be done. It could call cred an
> "Identity Server" and things like that. It could also not use "asynchronous"
> as selling point. Managers want to hear words they've already heard. They want
> to hear why Twisted isn't just something cobbled together by a bunch of geeks
> in their bedrooms.

It would be great. I'm also a manager, and have to convince also my
clients that twisted is good choice for us.