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