[Twisted-Python] Questions about adding documentation

Phil Christensen phil at bubblehouse.org
Fri Jul 31 11:57:32 MDT 2009


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




More information about the Twisted-Python mailing list