<div class="gmail_quote">On Fri, Jul 31, 2009 at 12:57 PM, Phil Christensen <span dir="ltr">&lt;<a href="mailto:phil@bubblehouse.org">phil@bubblehouse.org</a>&gt;</span> wrote:<br><blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;">
<div class="im"><br>
On Jul 31, 2009, at 1:34 PM, Kevin Horn wrote:<br>
&gt; &gt;Also, what do the Twisted core devs think about having a secondary<br>
&gt; &gt;wiki/cookbook thingy outside of the core docs?<br>
&gt;<br>
&gt; As a staging area for development of future core docs, I think I would<br>
&gt; recommend using a version control system (perhaps a distributed one),<br>
&gt; not a wiki.<br>
&gt;<br>
&gt; Agreed, wiki = yuck (for this).  Even as a &quot;staging ground&quot;.<br>
<br>
</div>Okay, tell me again what exactly the problem is with a wiki?<br>
<br>
I feel like the same thing happens every time we discuss<br>
documentation. Someone makes a recommendation to do it the easy way,<br>
and someone else dismisses any solution that doesn&#39;t satisfy their<br>
programmer&#39;s OCD.<br>
<br>
Yes, I&#39;d love to see version controlled XML documentation that adheres<br>
to a common writing style that is enforced across the board, but this<br>
talk has been happening for *YEARS* and there has been little<br>
improvement of significance (I have to emphasize that I understand a<br>
number of people have worked very hard on this, and I don&#39;t mean to<br>
denigrate their contributions).<br>
<br>
People keep telling me wikis are bad, but I&#39;m still not getting the<br>
&#39;why&#39; -- I just hear &quot;wikis are bad for documentation&quot; repeatedly<br>
presented as a fact.<br>
<br>
They do seem to work reasonably well for scores of other projects.<br>
<br>
PRAGMATISM!!! ;-)<br>
<font color="#888888"><br>
-phil<br>
</font></blockquote></div><br>Well, pragmatism is my basic reason for not liking wikis for docs. :)<br><br>For me, it boils down to every time I&#39;ve worked on or with a project that used wikis for docs (assuming that the project is of at least moderate size and has more than a couple of editors) that documentation has been terrible.  It&#39;s ended up as a disjointed mess, that&#39;s hard to navigate, and has a bajillion half-completed thoughts, and lots of outdated cruft.<br>
<br>Of course, some could say the same of (at least parts of) the current Twisted documentation. ;)<br><br>It&#39;s not that there&#39;s anything wrong with wiki&#39;s per se, it&#39;s just that they encourage &quot;bad habits&quot;.  If there were a solid editorial process in place, where someone was specifically responsible for reviewing, editing, splitting, merging, and correcting documents, then a wiki could probably work.  But I think it&#39;s easier to get coherent docs using tools that encourage &quot;good habits&quot;.<br>
<br>Obviously my definitions of &quot;good habits&quot; and &quot;bad habits&quot; are pretty vague...and not entirely spelled out even in my own mind.  Er, sorry about that...<br><br>Kevin Horn<br>