[Twisted-Python] Evangelism notes...

[Jeff Grimmett]

On 5/4/05, Itamar Shtull-Trauring <itamar at itamarst.org> wrote:
> 
> 
> Do you have any suggestions on how we can improve things? Besides "write
> more docs" which is basically always a given.
> 

OK, I'll bite at that one. Let me preface it with these two points:

1) On my development team, I'm the QA lead. We've encountered this same 
issue, with a different face, in the form of the lack of sufficient design 
documentation and code documentation of changes after the fact. It has 
caused serious issues down the road, both in software quality and in the 
quality of testing that QA provided. We've implemented some solutions that 
appear to work, and it's from that series of experiences that I am speaking.

2) I BELIEVE that this solution has been considered and discarded. I have 
suspicions why, which I will not speak of, but it's so OBVIOUS that I can't 
believe that a group of intelligent people would not have considered it. So 
I fear that I will be speaking to a wall here. So be it. 

My unsolicited advice: write the docs either before or during development. 

AFTER development is too late. Most developers have no interest in 
documentation (it's genetic or something) and want to move on to more "good 
stuff." It's OK, I understand, as everyone that enjoys coding understands it 
at a gut level. But the issue needs to be acknowledged before it can be 
dealt with.

The gist of the response I often seen with regards to Twisted documentation 
is along the lines of "I don't see the issue here - if you don't like the 
docs, write some." It seems to be a denial of the responsibility to write 
good documentation. *** I'm not saying that is in fact the case! *** I am 
saying that there is a perception. As one of my past bosses told me, 
"perception is everything in some circumstances." 

Here are the pitfalls (as I see them, YMMV) of retroactively writing 
documentation:

1) If the person writing the docs is not the person that designed and 
implemented, the *intent* of the class/module/etc being documented is not 
clear.

2) If the person writing the docs is not the person that implemented, then 
the person that implemented must be found, interrogated, and gone back to 
multiple times to get the docs right. (And if getting it right is not the 
goal, why bother?)

3) If the intent of the module/class/etc is not known beforehand, how does 
one determine if it is working right?

I don't mean to criticize, but this is in my eyes the greatest weakness of 
Twisted. My experiences with it, when it works, is that it works 
wonderfully. I can't commit to using it for anything critical, though, 
because I spend more time working around such gems as """I am a connector""" 
than I do in getting anything useful done.

I tell you: if it gets to the point where I SERIOUSLY consider writing my 
own simple frame work to get a job done as a TIME SAVING MEASURE then there 
is a problem, and I do not believe I am alone in this perception.

Take this in the spirit it is offered. I want to use Twisted for what I do, 
and I want it to succeed. 

-- 

Best,

Jeff
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://twistedmatrix.com/pipermail/twisted-python/attachments/20050504/eb9dccd1/attachment.htm