On 22 Jan, 10:14 pm, tom@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

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

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

On Feb 1, 2011, at 11:10 AM, Kevin Horn wrote:

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).

This seems to be the consensus about the finger tutorial from people who actually learned about twisted from it. It's effective documentation, although not perfect. On the other hand there's some sample bias, I hear a lot more from those people than from the people who couldn't learn about Twisted from it :). Arguments in favor of deleting it seem to be based mostly on difficulty of maintenance, which are valid, but perhaps overzealous. The finger tutorial seems better than nothing though, so how about this: we leave it around, but declare a moratorium on maintaining it, and anyone who wants to fix issues with the finger tutorial should be encouraged to write an entirely new tutorial instead, one that would be easier to keep up to date.