[Twisted-Python] Questions about adding documentation

[Phil Christensen]

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