On Tue, Feb 1, 2011 at 1:02 PM, <exar...@twistedmatrix.com> wrote: > On 22 Jan, 10:14 pm, t...@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
_______________________________________________ Twisted-Python mailing list Twisted-Python@twistedmatrix.com http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python
