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