[Twisted-Python] Documentation by newcomers (was Re: Using telnet or linereceiver protocol over ssh)

[Glyph]

On Jan 6, 2013, at 8:44 PM, Christopher Armstrong <radix at twistedmatrix.com> wrote:

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

I think I agree with all of that, Chris, although obviously my opinions differ from Jean-Paul's on this topic :).

To be fair I believe that it's not really feasible for someone new to the topic to write anything useful entirely, or even mostly, by themselves.  But if they write something basically sensible but with errors, it's easier for the experts to correct those flaws than to write something original.  (Assuming, of course, that the author has put enough effort into their writing that it basically hangs together and makes sense, even if it's not entirely correct or perfectly structured.)

The value of just prompting the experts to do something cannot be underestimated :).

-glyph

-------------- next part --------------
An HTML attachment was scrubbed...
URL: </pipermail/twisted-python/attachments/20130106/e21c7eaa/attachment.html>