[Twisted-Python] Questions about adding documentation

[Kevin Horn]

On Fri, Jul 31, 2009 at 12:57 PM, Phil Christensen <phil at 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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://twistedmatrix.com/pipermail/twisted-python/attachments/20090731/8b6691cb/attachment.htm