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

[jml at ids.org.au]

... is that we have no word for "entrepreneur".

Just had a conversation with a guy on #python, and he raised some valid
points. He appeared to be a programmer, and his concerns were focussed on his
job, and on pitching Twisted to mgmt.

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


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.

The Java website starts off with a page geared entirely towards management
(even if the headings don't say so), with all the useful programmer stuff
hidden away from view. Would it be a stupid idea to have:
- http://www.twistedmatrix.com/ : Twisted, the Framework of your Internet
- http://www.twistedmatrix.com/dev/ : You have been sucked into the vortex.
??

Or even dispense with a site that targets developers entirely, except for a
"This is why Twisted's technology is cool" page. After all, the grunts will be
happy with doco, and coders who want more than that will find it on the list
and the channel.


Thirdly, we should really, really, really get Coil done. This guy didn't
mention it, but I know many people (good programmers, even) who feel
uncomfortable at a command line, and much prefer web-based (or Windows-based)
administration. 

One of the cool things about Twisted is that it's extremely easy to start a
server for just about anything on your personal PC. This would be made much
more obvious with a GUI like Coil.


Now, all this is suggested humbly and tentatively. I'm not sure whether any of
these things are good things. I do know that they'd make ppl who I've worked
with in corporate environments more comfortable. (and not just the muppets)

I'm very interested in discussion, and what you all think of this. 

Also, I hope this email isn't critical in a vague way, and isn't
inflammatory. It's not meant that way, rather it's meant to note problems that
other people see and have told me, and to suggest ways of solving them.

cheers,
jml
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: not available
URL: </pipermail/twisted-python/attachments/20030605/f794211c/attachment.sig>