<div class="gmail_quote">On Fri, Jul 31, 2009 at 12:57 PM, Phil Christensen <span dir="ltr"><<a href="mailto:phil@bubblehouse.org">phil@bubblehouse.org</a>></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>
> >Also, what do the Twisted core devs think about having a secondary<br>
> >wiki/cookbook thingy outside of the core docs?<br>
><br>
> As a staging area for development of future core docs, I think I would<br>
> recommend using a version control system (perhaps a distributed one),<br>
> not a wiki.<br>
><br>
> Agreed, wiki = yuck (for this). Even as a "staging ground".<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't satisfy their<br>
programmer's OCD.<br>
<br>
Yes, I'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't mean to<br>
denigrate their contributions).<br>
<br>
People keep telling me wikis are bad, but I'm still not getting the<br>
'why' -- I just hear "wikis are bad for documentation" 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'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's ended up as a disjointed mess, that'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's not that there's anything wrong with wiki's per se, it's just that they encourage "bad habits". 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's easier to get coherent docs using tools that encourage "good habits".<br>
<br>Obviously my definitions of "good habits" and "bad habits" are pretty vague...and not entirely spelled out even in my own mind. Er, sorry about that...<br><br>Kevin Horn<br>