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