I've spent the past few days fighting with outdated Zope documentation and I got to thinking... has Mailman got updated docs for 2.1, or are people learning Mailman for the first time now suffering from the same "but that option doesn't exist in this version!" problems I'm having with Zope docs?
A quick look at list.org only turned up 2.0 documentation last updated a few years ago, although at least the FAQ looks more recent. Are newer docs in the works, or are we waiting for volunteers? Because if it's the latter, I've got some time right now that's not being spent fighting with Zope, and I don't mind volunteering to write some up-to-date stuff for 2.1.
I'm more of a coder than a writer, normally, but I've been doing a fair bit of writing lately and I've had to explain Mailman stuff to my list admins and users enough times that I should be good at this by now. :) I'd really hate for anyone to get the sort of negative impression of Mailman that I've gotten of Zope thanks to the documentation.
So if none of this is already happening... where would be best to start? I'd guess the user guide would be the first step, since I know as an admin I'd like to be able to point my users at a guide. :)
Terri
PS - If anyone wants to point me to more up-to-date Zope docs, I'd be much obliged. :)
"TO" == Terri Oda <terri@zone12.com> writes:
TO> I don't mind volunteering to write some up-to-date stuff for
TO> 2.1.Fame and fortune awaits you Terri!
A while back, I made a push towards writing the admin documentation, and the incomplete results can be found in CVS, under docs/mailman-admin.tex. That's in LaTeX using Python's mkhowto template. I'd like this to be the standard for Mailman's documentation because it's free, I already have the tool chain to build it, and I actually know it (as opposed to something like DocBook ;).
You should be able to get all the mkhowto tools by either grabbing the Python 2.2.2 source distro, or downloading the LaTeX version of the Python documentation:
http://www.python.org/doc/current/download.htmlI get it by checking out the Python cvs.
My vision is that there be three separate documents, one for users, one for admins, and one for site admins. The former would describe such things as subscribing and unsubscribing, viewing the archives, editing user options, getting explicit password reminders, choosing languages and digest modes, etc. I agree that this is the most important document to write -- even though I didn't start with it -- because there are many more users in the world than list or site admins.
The second document would describe everything an admin needs to know to run their lists, including email commands, approving posts and subscriptions, etc. This is the one I've started on. This is the second most important document.
The third is for the site admin and should cover such issues as installation, integration, editing mm_cfg.py, etc. Lots of this material should be available in the various READMEs.y
If you want to tackle the user guide, that would be wonderful. Definitely look at Chris Kolar's existing stuff, although I suspect lots of updates for 2.1 are necessary. Start by copying mailman-admin.tex and whacking out the text you don't need.
Tell me what I can do to help.
-Barry
participants (2)
-
barry＠python.org -
Terri Oda