On Fri, Jul 31, 2009 at 12:57 PM, Phil Christensen <phil@bubblehouse.org>wrote:
On Jul 31, 2009, at 1:34 PM, Kevin Horn wrote:
Also, what do the Twisted core devs think about having a secondary wiki/cookbook thingy outside of the core docs?
As a staging area for development of future core docs, I think I would recommend using a version control system (perhaps a distributed one), not a wiki.
Agreed, wiki = yuck (for this). Even as a "staging ground".
Okay, tell me again what exactly the problem is with a wiki?
I feel like the same thing happens every time we discuss documentation. Someone makes a recommendation to do it the easy way, and someone else dismisses any solution that doesn't satisfy their programmer's OCD.
Yes, I'd love to see version controlled XML documentation that adheres to a common writing style that is enforced across the board, but this talk has been happening for *YEARS* and there has been little improvement of significance (I have to emphasize that I understand a number of people have worked very hard on this, and I don't mean to denigrate their contributions).
People keep telling me wikis are bad, but I'm still not getting the 'why' -- I just hear "wikis are bad for documentation" repeatedly presented as a fact.
They do seem to work reasonably well for scores of other projects.
PRAGMATISM!!! ;-)
-phil
Well, pragmatism is my basic reason for not liking wikis for docs. :) 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. Of course, some could say the same of (at least parts of) the current Twisted documentation. ;) 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". 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... Kevin Horn