[Twisted-Python] Re: Documentation Standard (was: Re: [Twisted-Python] Documentation.. On a wiki!?)

Christopher Armstrong carmstro at twistedmatrix.com
Mon Feb 11 22:16:08 EST 2002

On Mon, 2002-02-11 at 21:28, Glyph Lefkowitz wrote:
> That said, I'd like to recommend against wiki for the following reasons:
> 1: it's not set in stone.  Users will come to it and it may be different
> than what they expected.

I didn't mean for the wiki to be the place for users to go to view the
documentation, only a place for collaborative development. See my
response to point #3 for more info on this.

Also, note that it is possible now to convert Moin to formats such as
DocBook, and once you get to that point, you can basically get to any
format (LaTeX included).

> 2: It tends to collect editorial annotations, and there's no structured
> way to remove them easily.  This will be confusing.

Nafai brought up this point, and I told him it was actually good that
they were there since it would be an incentive to fix stuff like "XXX:
This isn't clear!" before a release. But yeah, it's just not practical -
so if you really think it's ncessary, I'll write a tool to automatically
rip out editorial notes. It shouldn't be hard at all, and I don't think
it would be hard to get people to write editorial notes according to
some convention.

> 3: Partially because of 1: and 2:, Wikis are good for tightly knit
> communities, but what we need is external, end-user documentation, that
> will be read by people with no knowledge of how the system works

I of course would not have the wiki be the actual medium for
distribution/viewing by regular people. It will be released per-version
in the TwistedDocs package, and the API docs will only be a section
inside your main skeleton.

I'm also thinking of adding a user/password protection to the wiki so
only developers (or people we designate as documenters) can work on it.

> Wiki might be a great way to get the documentation process started, and
> a good place to publish drafts, but we already have IRC and cryptic
> references to the mailing list -- we need something that's a more
> gradual, high-quality introduction.

I don't see how wiki doesn't meet this.

And of course, as I probably don't need to mention, I think wiki is
great for this, because it makes documentation easy to work with through
a unified interface...

I'm also planning on putting the data on CVS so people can hack it with
their regular editors. I'll have to work something out where the wiki's
CVS repository will automatically update itself whenever someone commits
through CVS, but it shouldn't be a problem.

So, I'm going to attempt to submit a lot of documentation, to force you
to use the wiki! Then I will be the uber-documentation Twisted guy, and
you will all bow to me!! In the words of Moshe: "Muhahahahahaha!!!"


> On Mon, 2002-02-11 at 18:40, Andrew Bennetts wrote:
> > On Mon, Feb 11, 2002 at 02:46:39PM -0500, Christopher Armstrong wrote:
> > > So, the idea is to use MoinMoin for Twisted's documentation. I have the
> > > skeleton ported as well as one or two docs (and I'm working on
> > > transcribing the rest of the docs to fit this framework). So, this is my
> > > official submission for "what should Twisted use for documentation?". 
> > 
> > Interesting idea.  It's probably the most convenient format for quickly
> > writing nicely structured docs, and it is structured enough that you could
> > probably do a sane conversion to something else later, if desired.  In
> > short, I like it.
> -- 
> "Cannot stand to be one of many -- I'm not what they are."
>         -Guster, "Rocketship"
>                 glyph lefkowitz; ninjaneer, freelance demiurge
>     glyph @ [ninjaneering|twistedmatrix].com
                                Chris Armstrong
                         << radix at twistedmatrix.com >>

More information about the Twisted-Python mailing list