On Fri, Jul 31, 2009 at 12:11 PM, Jean-Paul Calderone <exarkun@divmod.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
On Fri, 31 Jul 2009 11:55:08 -0500, Kevin Horn <kevin.horn@gmail.com> wrote: 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.
True enough. And in my case, at least, navigation.
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.
I don't think using Lore is a problem particularly...but it need to be documented more clearly, and all in one place. Right now, there's stuff on the tracwiki, in the main docs, on the mailing list, etc. Particularly, the answers to the questions: - How do I build the documentation using Lore? - What is the Lore xhtml syntax, and how should I use it? - What is the process for making a documentation contribution? Please note, that I was originally suggesting Sphinx primarily as an alternative to a wiki-based system, rather than as a replacement for Lore...but the conversation kind of mutated. :)
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". IMO trac-wiki is really only suited for "marketing" type content.
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
_______________________________________________ Twisted-Python mailing list Twisted-Python@twistedmatrix.com http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python