On 5/4/05, <b class="gmail_sendername">Itamar Shtull-Trauring</b> <<a href="mailto:itamar@itamarst.org">itamar@itamarst.org</a>> wrote:<div><span class="gmail_quote"></span><blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;">
<br>Do you have any suggestions on how we can improve things? Besides "write<br>more docs" which is basically always a given.<br></blockquote></div><br>
OK, I'll bite at that one. Let me preface it with these two points:<br>
<br>
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.<br>
<br>
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. <br>
<br>
My unsolicited advice: write the docs either before or during
development. <br>
<br>
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.<br>
<br>
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." <br><br>
Here are the pitfalls (as I see them, YMMV) of retroactively writing documentation:<br>
<br>
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.<br>
<br>
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?)<br><br>
3) If the intent of the module/class/etc is not known beforehand, how does one determine if it is working right?<br>
<br>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.<br>
<br>
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.<br>
<br>
Take this in the spirit it is offered. I want to use Twisted for what I do, and I want it to succeed. <br>
<br>-- <br><br>Best,<br><br> Jeff<br>
<br>