[Twisted-Python] Questions about adding documentation
kevin.horn at gmail.com
Fri Jul 31 11:40:13 EDT 2009
On Fri, Jul 31, 2009 at 9:34 AM, Phil Christensen <phil at 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...
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 :)
-------------- next part --------------
An HTML attachment was scrubbed...
More information about the Twisted-Python