-----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----- _______________________________________________ Mailman-Developers mailing list Mailman-Developers@python.org http://mail.python.org/mailman/listinfo/mailman-developers Mailman FAQ: http://www.python.org/cgi-bin/faqw-mm.py Searchable Archives: http://www.mail-archive.com/mailman-developers%40python.org/ Unsubscribe: http://mail.python.org/mailman/options/mailman-developers/archive%40jab.org Security Policy: http://www.python.org/cgi-bin/faqw-mm.py?req=show&file=faq01.027.htp
