<div class="gmail_quote">On Fri, Jul 31, 2009 at 9:34 AM, Phil Christensen <span dir="ltr"><<a href="mailto:phil@bubblehouse.org">phil@bubblehouse.org</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">On Jul 31, 2009, at 10:19 AM, Santiago Aguiar wrote:<br>
> It could also be a good idea to try to make it more wiki-like at the<br>
> beginning; I think there's quite a lot of people that would like to<br>
> contribute with this, but having different documents/styles for<br>
> different areas of the doc is not good, a wiki like doc might allow<br>
> some<br>
> people to work on giving a more cohesive look to the whole doc, and<br>
> others to add the meat and bones, provide examples, etc, while<br>
> allowing<br>
> everyone to review it easily. Thinking about it, of course a doc on<br>
> SVN<br>
> would help in the same way ;).<br>
<br>
</div>I'd like to second this, for at least the third or fourth time over<br>
the last several years ;-)<br>
<br>
To respond in advance to previous criticisms of the idea:<br>
<br>
* wiki syntax sucks<br>
* it doesn't have an acceptable form of version control<br>
* it's frustrating that it can't be easily bundled with<br>
a release tarball<br>
* the same info is on the mailing list, just use google<br>
to find it<br>
<br>
All 100% true. Nevertheless, I say wiki. It would provide the least<br>
complicated route for new users to document things they discover<br>
during the learning process, which is *exactly* the phase that is so<br>
hard for the more experienced users to properly explain.<br>
<br>
Hopefully over time the various technical writers who volunteer often<br>
could rewrite this content into the formal collection that is<br>
distributed with Twisted proper, but in the meantime, a community-<br>
edited wiki would also provide another window into the community for<br>
new developers.<br>
<br>
I also would recommend MediaWiki. Yes, less than perfect, not as good<br>
as this, that, or the other wiki. In the interest of keeping the bar<br>
for entry low, however, we would be harnessing a familiarity with<br>
MediaWiki provided by exposure to Wikipedia.<br>
<br>
Pragmatism, not idealism, and all that...<br>
<font color="#888888"><br>
-phil<br>
</font><div><div></div><div class="h5"></div></div></blockquote><div><br>Well, if there *were* to be a change in the documentation system used, I would push for moving to Sphinx, rather than a wiki.<br><br>* it's rapidly becoming a "standard" for docs in the Python world<br>
* it has lots of neat features<br>* it can be version controlled<br>* multiple output formats (html, chm, Latex(and therefore PDF), etc.)<br>* I just like it :)<br><br>Just sayin'<br><br>Kevin Horn <br></div></div><br>