[Twisted-Python] Questions about adding documentation

Glyph Lefkowitz glyph at twistedmatrix.com
Fri Jul 31 14:23:49 MDT 2009


On Fri, Jul 31, 2009 at 1:16 PM, Jessica McKellar <
jessica.mckellar at gmail.com> wrote:

> I am not scared off. In fact, I'm updating the
> wiki/ContributingToTwistedLabs and related how-to-edit-documentation pages
> right now.
>

I see the edits in the timeline.  They look great!  Thanks! :-D

Do you have any ideas for improving the front page as well?  I think the
random-list-of-links approach to its information architecture hasn't been
terribly effective.

I think adding content to and restructuring the howtos gives me a full plate
> already, and to be honest I'm more interested in the content than the
> presentation.


This is good to hear.  I think it should definitely be our first priority.

Thanks for all the help and feedback, everyone.
>

Please don't hesitate to ask for any other help or feedback you might need.

People who have more experience with the successes and failures of the
> various ways to organize project content online can make that decision (...)


I don't want to stifle the possible discussion of using a different system,
but for those of you interested in switching to Sphinx or something else,
there are several things you need to address:

First and foremost, you need to make a commitment to *maintaining* the
documentation infrastructure.  This includes teaching other folks how to use
it.

Second, you need to submit a complete proposal.  This means we need a clear
enumeration of what benefits the different documentation technology will
have; this needs to be written up in one place so that we can evaluate it
and discuss it without chasing down a million little email threads or ticket
comments.

Such a proposal also needs to address integration of automated testing and
automated doc-building with the examples.  You'll need to set up a builder
that will replace our current documentation builder.  You'll need to update
all the relevant wiki pages.

Third, you need to address the transition plan.  Just translating all the
documentation by hand is a possibility, but it has potential problems.  What
happens if we discover a problem with the new tool?  How do we roll back?

and I'd happily help move content over to another format should that be
> necessary.


Lucky for you, Jessica appears to have volunteered to do this for you :-).
(You might want to confirm that first, though.)

I certainly wouldn't mind switching to a tool that has lots of fancy
features that lore lacks, but a hit-and-run approach where we just switch
tools in the hopes that it will make something better may leave us in a
worse situation than we already are.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: </pipermail/twisted-python/attachments/20090731/4b1f3f28/attachment.html>


More information about the Twisted-Python mailing list