[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