[Mailman-Developers] Documentation status?

[Barry Warsaw]

-----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-----