[Twisted-Python] Questions about adding documentation

[Kevin Horn]

On Fri, Jul 31, 2009 at 12:11 PM, Jean-Paul Calderone <exarkun at divmod.com>wrote:

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

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 at twistedmatrix.com
> http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://twistedmatrix.com/pipermail/twisted-python/attachments/20090731/528ff578/attachment.htm