[Twisted-Python] Questions about adding documentation

[Jean-Paul Calderone]

On Fri, 31 Jul 2009 11:55:08 -0500, Kevin Horn <kevin.horn at gmail.com> wrote:
> [snip]
>
>I'd love to see a documentation "reboot" using Sphinx, but not if it's going
>to be a half-baked, never-finished project.
>
> [snip]
>
>I'd also be interested in hearing the opinions of some of the core Twisted
>guys on the various things we've been talking about here.  What do you guys
>think about using a different docs system than what is being used now?  If
>you guys are all dead set against it, there's not much point hashing out the
>details...

I don't find that people trying to use Twisted complain about the
presentation of the documentation.  I find that they complain about
its content.

So, I think that it's the content that needs to be addressed.  I don't
*think* that switching to Sphinx (or anything else) is going to make any
different to the content of the current documentation.  One might argue
that Lore is a significant barrier to entry for new contributions to the
documentation, but you'd have to try pretty hard to convince me.  Pretty
much anyone can write some simple (Lore x)html.  And if they can't, then
there are other people willing to translate plain text into Lore input
documents.

>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.

As something intended to be user-facing, I don't think it's a great idea.
Of course, there *is* a wiki hosted on the website already...  And it has
some documentation on it...  So what's being proposed, exactly? :)

Obviously I'm speaking for myself, not for all the other people who have
contributed to Twisted.

Jean-Paul