<div class="gmail_quote">On Tue, Feb 1, 2011 at 1:02 PM, <span dir="ltr"><<a href="mailto:exarkun@twistedmatrix.com">exarkun@twistedmatrix.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin: 0pt 0pt 0pt 0.8ex; border-left: 1px solid rgb(204, 204, 204); padding-left: 1ex;">
<div class="im">On 22 Jan, 10:14 pm, <a href="mailto:tom@recursivedream.com">tom@recursivedream.com</a> wrote:<br>
>In this thread, I hope to find a resolution to the issue of the Finger<br>
>tutorial and efforts to sufficiently improve it or remove it.<br>
><br>
>In the course of reviewing documentation-related tickets, I stumbled<br>
>upon<br>
>#1148 (<a href="http://twistedmatrix.com/trac/ticket/1148" target="_blank">http://twistedmatrix.com/trac/ticket/1148</a>). Therein, Glyph<br>
>first(?)<br>
>put down a lot of things we've been discussing and agreeing upon in the<br>
>Refactoring Documentation thread. One of the issues still up for debate<br>
>is<br>
>whether or not the Finger tutorial is sufficiently strong to survive<br>
>the<br>
>documentation overhaul. There are various points against it right now:<br>
><br>
</div>> - It isn't tested or even test*able*<br>
> - It doesn't cover "best practices" as they relate to writing<br>
<div><div></div><div class="h5">>testable,<br>
> maintainable code, etc.<br>
> - It attempts to implement basically every main Twisted concept,<br>
>often in<br>
> contrived or poorly-executed ways<br>
> - It has been said it has, "...at best, the potential for<br>
>mediocrity."<br>
><br>
>There are also enough tickets related to refactoring / rewriting it<br>
>that a<br>
>resolution would make a significant dent in the list of stale<br>
>documentation<br>
>tickets. Among these two year-old tickets are:<br>
><br>
> - <a href="http://twistedmatrix.com/trac/ticket/532" target="_blank">http://twistedmatrix.com/trac/ticket/532</a> - Big jump from<br>
>finger18.py to<br>
> finger19.py in tutorial<br>
> - <a href="http://twistedmatrix.com/trac/ticket/626" target="_blank">http://twistedmatrix.com/trac/ticket/626</a> - Split tutorial finger<br>
>code<br>
> into libraries<br>
> - <a href="http://twistedmatrix.com/trac/ticket/2205" target="_blank">http://twistedmatrix.com/trac/ticket/2205</a> - Documentation<br>
>codelistings<br>
> need updating and tests<br>
><br>
>This shouldn't be a blocker on anything Kevin and I are doing, but it'd<br>
>be<br>
>nice to concurrently have discussions on issues we'll need to address<br>
>later.<br>
>I'm also pretty anal about ticket lists and if these aren't going<br>
>anywhere<br>
>I'd love to close them ;)<br>
<br>
</div></div>In an attempt to elicit some feedback on this, let me try casting the<br>
issue in a different light.<br>
<br>
Does anyone think the finger tutorial shouldn't be deleted? Why?<br>
<br>
Jean-Paul<br>
<br></blockquote></div><br>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).<br>
<br>Kevin Horn<br>