[Twisted-Python] Fingering Finger

[Kevin Horn]

On Tue, Feb 1, 2011 at 1:02 PM, <exarkun at twistedmatrix.com> wrote:

> On 22 Jan, 10:14 pm, tom at recursivedream.com wrote:
> >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 ;)
>
> In an attempt to elicit some feedback on this, let me try casting the
> issue in a different light.
>
> Does anyone think the finger tutorial shouldn't be deleted?  Why?
>
> Jean-Paul
>
>
I actually found it very helpful back when I was first learning Twisted.  I
admit I haven't really read it critically in several years though.  If it is
to be removed, I think it would be a good idea to replace it with something
similar (i.e. a step-by-step implementation of a protocol).

Kevin Horn
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://twistedmatrix.com/pipermail/twisted-python/attachments/20110201/f6bafd64/attachment-0001.htm