[Twisted-Python] Using telnet or linereceiver protocol over ssh

[Christopher Armstrong]

On Sun, Jan 6, 2013 at 9:57 PM, <exarkun at twistedmatrix.com> wrote:

> On 02:23 am, glyph at twistedmatrix.com wrote:
>
> >In a way, it is best to work on documentation when you don't yet fully
> >understand, because if you fully understand you yourself don't need the
> >documentation any more :).
>
> As I may have mentioned before, I strongly disagree with this.
>
> It is much easier to (*correctly*) explain something you already
> understand, all other things being equal.
>
> The factor that seems to lead people to suggest that people who don't
> understand a thing write documentation for that thing is that once you
> understand it, you don't *want* the documentation *for yourself*
> anymore, which removes one possible motivation for creating it.
>
> But no matter how much we might want to exploit this motivation in
> people, it doesn't mean that the result will be good documentation.
>
> Jean-Paul
>
>
I agree with Jean-Paul. Writing documentation in ignorance (no offense
intended to any party) is not a good way to write good documentation. I
think we've seen a number of attempts at this that have resulted in pretty
shoddy documentation. I do think, however, that *right after you learn*
something you are in a good position to benefit the documentation of the
project.

The argument has also been made (not in this thread; I mean in general)
that the process of learning something allows one to structure
documentation about it in a way that applies well to another person
learning something, but I think that concept has flaws as well. I think
that a common result of such attempts is that someone will hit a common
blocker in understanding their subject and then go off on a number of
misguided tangents, and then when they finally come to understand the
subject their sudden insight becomes associated in their mind with the
resolution of the misguided attempts.

But that's all just conjecture and isn't really core to my point.

I think despite all these problems with writing as one learns, it's
valuable to make an attempt at writing some documentation as one learns
something, as long as there is a sincere modesty on one's part and a
willingness to let their documentation be seriously overhauled or at least
critiqued by the real experts on the subject (assuming those experts can
muster the time to do the critiquing or overhauling).

-- 
Christopher Armstrong
http://radix.twistedmatrix.com/
http://planet-if.com/
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://twistedmatrix.com/pipermail/twisted-python/attachments/20130106/4156c055/attachment.htm