<div class="gmail_quote">On Fri, Jul 31, 2009 at 1:16 PM, Jessica McKellar <span dir="ltr"><<a href="mailto:jessica.mckellar@gmail.com">jessica.mckellar@gmail.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;">
I am not scared off. In fact, I'm updating the wiki/ContributingToTwistedLabs and related how-to-edit-documentation pages right now.<br></blockquote><div><br>I see the edits in the timeline. They look great! Thanks! :-D<br>
<br>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.<br><br></div><blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;">
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.</blockquote><div><br>This is good to hear. I think it should definitely be our first priority.<br>
<br>
<blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;">Thanks for all the help and feedback, everyone.<font color="#888888"><br></font></blockquote>
<br>Please don't hesitate to ask for any other help or feedback you might need.<br><br></div><blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;">
People who have more experience with the successes and failures of the various ways to organize project content online can make that decision (...)</blockquote><div><br>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:<br>
<br>First and foremost, you need to make a commitment to <i>maintaining</i> the documentation infrastructure. This includes teaching other folks how to use it.<br><br>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.<br>
<br>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.<br>
<br>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?<br>
<br><blockquote style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;" class="gmail_quote"> and I'd happily help move content over to another format should that be necessary. </blockquote>
<div> </div>Lucky for you, Jessica appears to have volunteered to do this for you :-). (You might want to confirm that first, though.)<br><br>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.<br>
<br></div></div>