<div class="gmail_quote">On Fri, Jul 31, 2009 at 12:11 PM, Jean-Paul Calderone <span dir="ltr"><<a href="mailto:exarkun@divmod.com">exarkun@divmod.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;">
On Fri, 31 Jul 2009 11:55:08 -0500, Kevin Horn <<a href="mailto:kevin.horn@gmail.com">kevin.horn@gmail.com</a>> wrote:<br>
> [snip]<br>
<div class="im">><br>
>I'd love to see a documentation "reboot" using Sphinx, but not if it's going<br>
>to be a half-baked, never-finished project.<br>
><br>
</div>> [snip]<br>
<div class="im">><br>
>I'd also be interested in hearing the opinions of some of the core Twisted<br>
>guys on the various things we've been talking about here. What do you guys<br>
>think about using a different docs system than what is being used now? If<br>
>you guys are all dead set against it, there's not much point hashing out the<br>
>details...<br>
<br>
</div>I don't find that people trying to use Twisted complain about the<br>
presentation of the documentation. I find that they complain about<br>
its content.<br>
</blockquote><div><br>True enough. And in my case, at least, navigation.<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>
So, I think that it's the content that needs to be addressed. I don't<br>
*think* that switching to Sphinx (or anything else) is going to make any<br>
different to the content of the current documentation. One might argue<br>
that Lore is a significant barrier to entry for new contributions to the<br>
documentation, but you'd have to try pretty hard to convince me. Pretty<br>
much anyone can write some simple (Lore x)html. And if they can't, then<br>
there are other people willing to translate plain text into Lore input<br>
documents.<br>
<div class="im"></div></blockquote><div><br>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.<br>
<br>Particularly, the answers to the questions:<br>- How do I build the documentation using Lore?<br>- What is the Lore xhtml syntax, and how should I use it?<br>- What is the process for making a documentation contribution?<br>
<br>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. :)<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;">
<div class="im">
>Also, what do the Twisted core devs think about having a secondary<br>
>wiki/cookbook thingy outside of the core docs?<br>
<br>
</div>As a staging area for development of future core docs, I think I would<br>
recommend using a version control system (perhaps a distributed one),<br>
not a wiki.<br>
</blockquote><div><br>Agreed, wiki = yuck (for this). Even as a "staging ground". <br><br>IMO trac-wiki is really only suited for "marketing" type content. <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;">
<br>
As something intended to be user-facing, I don't think it's a great idea.<br>
Of course, there *is* a wiki hosted on the website already... And it has<br>
some documentation on it... So what's being proposed, exactly? :)<br>
<br>
Obviously I'm speaking for myself, not for all the other people who have<br>
contributed to Twisted.<br>
<font color="#888888"><br>
Jean-Paul<br>
</font><div><div></div><div class="h5"><br>
_______________________________________________<br>
Twisted-Python mailing list<br>
<a href="mailto:Twisted-Python@twistedmatrix.com">Twisted-Python@twistedmatrix.com</a><br>
<a href="http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python" target="_blank">http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python</a><br>
</div></div></blockquote></div><br>