<div class="gmail_quote">On Fri, Jul 31, 2009 at 11:14 AM, Santiago Aguiar <span dir="ltr"><<a href="mailto:santiago.aguiar@gmail.com">santiago.aguiar@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;">
<div class="im">Reza Lotun wrote:<br>
> Rather than change the documentation system entirely, who don't we<br>
> just create a new resource for Twisted documentation - a Twisted<br>
> Documentation Wiki. At the very least it can be a repository of<br>
> various tips and tricks we happen to find, and maybe it can even be a<br>
> staging ground for documentation that makes it into Twisted proper.<br>
><br>
</div>Even if I re-suggested the wiki based documentation, I think it's<br>
important to be extra careful on how it's used. One thing I personally<br>
hate is projects whose documentation is basically wiki-based, and what<br>
you end having is a disconnected set of tips, many out of date, of how<br>
to do this and that. It could be OK it it's labeled 'Tipi-wiki' but not<br>
'Documentation' :).</blockquote><div><br>In my experience, this what happens to every project that a) uses a wiki for core documentation and b) has more than one person editing the wiki.<br></div><blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;">
<br>
<br>
As you say, I think that the wiki could be useful as a staging ground to<br>
build a formal documentation, but it shouldn't be even suggested for new<br>
users, since what they will probably find are many unfinished ideas.<br>
<br>
Alternatively, a separate doc repo with sphinx based doc could be built<br>
so that it will allow for collaborative development making clear that is<br>
a work in progress and a product with 'releases'. I say a different repo<br>
to avoid having to give commit access to code for people who are working<br>
on doc, maybe same repo with different permissions would be better. And<br>
I suggest sphinx to a) start from scratch and add existing doc as we see<br>
it's relevant, b) have a more flexible base than HTML docs, and for the<br>
reasons mentioned by Kevin (plus I want to learn it :P).<br>
<br>
--<br>
<font color="#888888">Santiago.<br>
</font><div><div></div><div class="h5"><br>
</div></div></blockquote></div><br>I'd love to see a documentation "reboot" using Sphinx, but not if it's going to be a half-baked, never-finished project.<br><br>Since Jessica started this thread, and is the only person (so far) who has given any sort of commitment to actually working on new/revised docs, I'd really like to hear her opinion.<br>
<br>Jessica? You still out there? Hope we haven't scared you off...<br><br>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...<br>
<br>Also, what do the Twisted core devs think about having a secondary wiki/cookbook thingy outside of the core docs?<br><br>Kevin Horn<br>