[Mailman-Developers] Documentation status?

[Terri Oda]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

On 5-Mar-08, at 5:26 PM, Barry Warsaw wrote:
> I like having docs in the wiki because it lets more people
> contribute.  The downside is that you can't reach it when you're
> offline and it's harder to publish in alternative media.  Have you
> thought at all about how to handle that?

I've actually thought about it a fair bit!  I also like the wiki  
'cause it's easier for other people to contribute (because I like to  
believe that I'm not the only person in the world who wants to write  
extensive Mailman documentation ;)  ), and I'm particularly fond of  
the wiki we're using on wiki.list.org because of the way it outputs.

PDF:

One of the things I really like about the Confluence wiki software is  
that it does a pdf export.  I was *shocked* by how many people want  
to print mailman documentation but apparently that pdf appeals to a  
lot of people (I used to get more mail about that format than any  
other).

I noticed today that the pdf export isn't available if you're not  
logged in, though.  Can we change that?  I didn't see it offhand in  
the settings, but I admit I haven't looked very hard yet.  I really  
think people will use it if they know it's there.

HTML:

What *is* available even if you're not logged in, though, is a nice  
printable version of the HTML.   We could probably make a plain text  
version from this, although I'm unconvinced anyone would care except  
in a theoretical way. ;)  Are there other formats that would be  
useful? When people emailed me and mentioned format, they were almost  
all using PDF or HTML, so I assume those are the most important ones.

Printed hard copies:

I've been putting the manuals into big wiki documents rather than  
splitting them up -- easier for those who want a printout to get it  
in a go.  (The appendices are separate 'cause I didn't think most  
people would want them, and those who did would probably want them  
separate.)  They can print as pdf or as html, as per their  
preferences, or import the HTML into something and repaginate however  
they like.  I haven't actually tried this, but it really is nice html  
output. :)

Including the docs with releases?:

The HTML output is nice enough that I think we could consider  
snapshotting the documentation and putting it with each release as  
HTML.   I think the Members Manual is worth including particularly  
because so many people have it on their sites for their users  
already.  Plus, with a couple of search and replaces, you can  
customize the whole thing for your site, or even for a specific list,  
which can be very handy for certain types of users.  I'm hoping the  
List Administrators Manual will be worth including when it's done,  
too, as well as the as of yet unwritten Site Administrators  
Manual.... but maybe I'm getting ahead of myself.  Still, I think  
we'd do well to include some of this with the release.  I will even  
volunteer to proofread the wiki output for each release.  (I edited a  
magazine for years, I can probably handle this.)

Doc licensing:

I periodically get emails asking about the license on the  
documentation.  I kinda assume it's all GPL (I can sign another  
copyright form for them if you need me to, Barry.), and that makes  
most sense if we want to include them.  If everyone's okay with that,  
we should maybe put a note to that effect so I don't have to keep  
telling people "Please, take it and do anything you want with it!  I  
like people using mailman, and if my docs help you do that, use them  
any way you need to!" Or, hrm, maybe I'll just put that in the docs  
and it'll get the point across. :)

Other docs I want to see in the wiki:

In my perfect world, I'd like to see us port all of our FAQ items to  
the documentation part of the wiki, so all of these things could be  
found in one place and thus easily searchable in one go.  Any  
volunteers?  Easy job, just a bit time-consuming, and a bit of  
thought needs to be put into how best to organize things.  My guess  
is make them all children of an FAQ page so they're automatically  
indexed, but keep things one-question-per-page since it's unlikely  
that anyone'll ever want to print the entire FAQ.

Similarly, installation docs, things like the backscatter  
information... all should be in one place.  I was trying to explain  
to one of my department sysadmins where to find mailman help, and it  
was *embarrassing* when I started listing off the docs I wrote, the  
FAQ Wizard, the mailing lists, the help files included with the  
installation, the FAQ on list.org... really, I'd like to see a one- 
stop shop for documentation, and I think the wiki is the best choice  
(because more people can contribute!), with us exporting the bits  
that are useful to go with each release.

I periodically try to coerce my little sister to import everything  
into the wiki for me, but she is strangely resistant to my offer of  
cookies in exchange for mind-numbing work. ;)    But it is a pretty  
easy job with a script and some time to sanity-check the results, if  
anyone's got some time and interest.  As added incentive, the offer  
of fresh cookies is open to anyone, not just my sister.  I'll mail  
them out to any address you like, although obviously I can't  
guarantee that they'll be quite as fresh by the time you get 'em. ;)

Finally:

Jeez, what an essay.  I could have written something explaining all  
the general list administration options in the time it took me to  
type this. Whoops.  sorry!

  Terri

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.7 (Darwin)

iD8DBQFHz6lNYWvHDqWmQaoRAplHAJ9aJMOxm5HR+nbQOgtrvddzcoeP2wCfUvJK
lkwPNP+s0kRm0aHRLgHMTYU=
=Bq22
-----END PGP SIGNATURE-----