[Twisted-Python] Questions about adding documentation
phil at bubblehouse.org
Fri Jul 31 13:57:32 EDT 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
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.
More information about the Twisted-Python