[Twisted-Python] Evangelism notes...
Jeff Grimmett
grimmtooth at gmail.com
Wed May 4 20:40:34 EDT 2005
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
More information about the Twisted-Python
mailing list