[Twisted-Python] Fingering Finger

[Tom Davis]

In this thread, I hope to find a resolution to the issue of the Finger
tutorial and efforts to sufficiently improve it or remove it.

In the course of reviewing documentation-related tickets, I stumbled upon
#1148 (http://twistedmatrix.com/trac/ticket/1148). Therein, Glyph first(?)
put down a lot of things we've been discussing and agreeing upon in the
Refactoring Documentation thread. One of the issues still up for debate is
whether or not the Finger tutorial is sufficiently strong to survive the
documentation overhaul. There are various points against it right now:

   - It isn't tested or even test*able*
   - It doesn't cover "best practices" as they relate to writing testable,
   maintainable code, etc.
   - It attempts to implement basically every main Twisted concept, often in
   contrived or poorly-executed ways
   - It has been said it has, "...at best, the potential for mediocrity."

There are also enough tickets related to refactoring / rewriting it that a
resolution would make a significant dent in the list of stale documentation
tickets. Among these two year-old tickets are:

   - http://twistedmatrix.com/trac/ticket/532 - Big jump from finger18.py to
   finger19.py in tutorial
   - http://twistedmatrix.com/trac/ticket/626 - Split tutorial finger code
   into libraries
   - http://twistedmatrix.com/trac/ticket/2205 - Documentation codelistings
   need updating and tests

This shouldn't be a blocker on anything Kevin and I are doing, but it'd be
nice to concurrently have discussions on issues we'll need to address later.
I'm also pretty anal about ticket lists and if these aren't going anywhere
I'd love to close them ;)


Cheers,

Tom
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://twistedmatrix.com/pipermail/twisted-python/attachments/20110122/fc67cab4/attachment.htm