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