<div dir="ltr">On Sun, Jan 6, 2013 at 9:57 PM, <span dir="ltr"><<a href="mailto:exarkun@twistedmatrix.com" target="_blank">exarkun@twistedmatrix.com</a>></span> wrote:<br><div class="gmail_extra"><div class="gmail_quote">
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div class="im">On 02:23 am, <a href="mailto:glyph@twistedmatrix.com">glyph@twistedmatrix.com</a> wrote:<br><br>
>In a way, it is best to work on documentation when you don't yet fully<br>
>understand, because if you fully understand you yourself don't need the<br>
>documentation any more :).<br>
<br>
</div>As I may have mentioned before, I strongly disagree with this.<br>
<br>
It is much easier to (*correctly*) explain something you already<br>
understand, all other things being equal.<br>
<br>
The factor that seems to lead people to suggest that people who don't<br>
understand a thing write documentation for that thing is that once you<br>
understand it, you don't *want* the documentation *for yourself*<br>
anymore, which removes one possible motivation for creating it.<br>
<br>
But no matter how much we might want to exploit this motivation in<br>
people, it doesn't mean that the result will be good documentation.<br>
<span class="HOEnZb"><font color="#888888"><br>
Jean-Paul<br>
</font></span><div class="HOEnZb"><div class="h5"><br></div></div></blockquote><div><br></div><div style>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.</div>
<div style><br></div><div style>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.</div>
<div style><br></div><div style>But that's all just conjecture and isn't really core to my point.</div><div style><br></div><div style>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).</div>
</div><div><br></div>-- <br>Christopher Armstrong<br><a href="http://radix.twistedmatrix.com/">http://radix.twistedmatrix.com/</a><br><a href="http://planet-if.com/">http://planet-if.com/</a><br><br>
</div></div>