[Twisted-Python] Fingering Finger

[Andrew Gasson]

On 1/02/2011, at 7:10 PM, Kevin Horn wrote:

> 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

I hate deleting anything as there could be good tidbits there for someone. Can we just depreciate it and but strong warning at top of all finger docs to say they are outdated and maynot be the current best practice ?

Gas

> _______________________________________________
> Twisted-Python mailing list
> Twisted-Python at twistedmatrix.com
> http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python

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