[Twisted-Python] Questions about adding documentation

Kevin Horn 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...
>
> -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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://twistedmatrix.com/pipermail/twisted-python/attachments/20090731/84214411/attachment.htm 


More information about the Twisted-Python mailing list