[Twisted-Python] Documentation.. On a wiki!?
Yes, that's right. http://twistedmatrix.com/users/carmstro.twistd/static/moin/wiki/cgi-bin/moin... (ok, yeah, it's a long URL. deal.) 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?". Yes, I do realize that I'll probably need to make lots of customizations for this to work well, and maybe even some tools for dealing with the wiki without using the web. (ie, CLI tools etc). -- Chris Armstrong << radix@twistedmatrix.com >> http://twistedmatrix.com/users/carmstro.twistd/
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. Another advantage is you could probably easily link to Teud docs of the Twisted API. I've already privately mailed Glyph expressing my interest in helping out with the documentation; after I get home from work I'll try to remember to add my twisted.enterprise tutorial to your Wiki. -Andrew.
On Mon, 2002-02-11 at 19:40, Andrew Bennetts wrote:
I've already privately mailed Glyph expressing my interest in helping out with the documentation; after I get home from work I'll try to remember to add my twisted.enterprise tutorial to your Wiki.
-Andrew.
Excellent. I was actually planning on doing it myself, so now I can get on to other things. Thanks for helping out! -- Chris Armstrong << radix@twistedmatrix.com >> http://twistedmatrix.com/users/carmstro.twistd/
There is a place for wiki, but I don't think it's the same as a place for docs. However, since I don't think I've said it on the mailing list yet, I'd like to state that my official position on the issue of documentation standards is that there is no documentation standard until somebody decides to make one. Personally I think I'm going to work in LaTeX or maybe DocBook when I've got some time. However, if you want to submit some docs, please submit them in any format that you feel like: content is more important than format right now. Whoever submits the most quality docs the fastest (and this is essentially an arbitrary decision on my part, I know) will become the documentation maintainer and I will use whatever format they used for a standard. 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. 2: It tends to collect editorial annotations, and there's no structured way to remove them easily. This will be confusing. 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 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. 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
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!!!" :-D
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@twistedmatrix.com >> http://twistedmatrix.com/users/carmstro.twistd/
On Mon, Feb 11, 2002 at 08:28:36PM -0600, Glyph Lefkowitz wrote:
There is a place for wiki, but I don't think it's the same as a place for docs. [...] 1: it's not set in stone. Users will come to it and it may be different than what they expected.
Hah! And twisted itself is? :-) I would think users would come to it, and if it doesn't explain something they had a problem with, they will add something that does. This is the reason _not_ to allow only developer contributions. -- ---------------------------------------------------------------------- ABO: finger abo@minkirri.apana.org.au for more info, including pgp key ----------------------------------------------------------------------
participants (4)
-
abo＠minkirri.apana.org.au -
andrew＠ritsuko.xware.cx -
Christopher Armstrong -
Glyph Lefkowitz