-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 On Mar 6, 2008, at 3:20 AM, Terri Oda wrote:
> -----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. Heh, just goes to show you how clueless /I/ am! I'd never played with that before, but, like, WOW. :)n > 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. Yep, changed. There are two permissions that control this, one for page exports and one for space exports. I don't see any reason why these shouldn't be enabled for anonymous users, since we already allow viewing for anonymous users. This has to be done on a per-space basis, so I enabled both page and space export for the Development, Documentation, Community, and Security spaces. > 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. These days, I think you're right about that. Let's call YAGNI on other formats. > 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. :) Cool. > 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.) That would be great, very much appreciated! I think it would be fairly easy to get my release script to hit the PDF export links to download the latest copies when we spin the tarballs. > 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. :) I think the GFDL would probably be more appropriate: http://www.gnu.org/licenses/licenses.html#FDL I'm not as well versed on this license; what do people think about that? > 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? Yes! > 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 agree completely. > 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. ;) :) Maybe I'll have more luck bribing my son with Bionicles. :) > 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 No, that was great Terri, thanks! I think you're definitely on the right track with this and I really appreciate everything you've done to help coordinate the documentation effort. - -Barry -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.8 (Darwin) iEYEARECAAYFAkfRY/cACgkQ2YZpQepbvXEo9ACgh2IVcf5mfkrn5BG5zqRMcYu4 Gx0AmgNzoBk/dJpSsY/3aWGRTMwElBD+ =/fMT -----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
