On Fri, Jul 31, 2009 at 1:16 PM, Jessica McKellar < jessica.mckellar@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.