[Mailman-Developers] Documentation status?

[Terri Oda]

On 11-Mar-08, at 11:00 AM, Jason Pruim wrote:
> I can work on that... I already have a wiki account, and it looks  
> like I can edit pages... I would like to get some opinions on how  
> to do the FAQ's... I have some for my company website (Not related  
> to mailman) but what I did was a list of all the questions up at  
> the top of the page with named anchors linking down to the actual  
> answer... Maybe the best way to describe it would be to show you..  
> Sorry if this is bad form... Just trying to help! :)
>
> http://raoset.com/faqs/faqs.shtml
>
> Let me know if that looks like a good way for these... I can make  
> the transfer pretty quickly if this looks like it would be a good  
> thing. Or if anyone has any better ideas on how to do them, I'm  
> open to ideas :)

I like this style when you have a smaller number of questions, but  
there are probably over 200 entries in the the Mailman FAQ.  I think  
putting them all on one page is less than ideal:

(a) It makes for a big, unpleasant to load page
(b) It makes it awkward to print off the answer to a specific  
question (seriously, people seem to print docs a lot.  I don't get  
it, but I'm learning to expect it)
(c) It makes it more difficult to edit (our wiki doesn't seem to let  
you edit a single section of a document)

Even split up by section as we have it now, there are 30+ questions  
in a lot of the sections, so they'd still be pretty big.  I find  
editing the Members Manual actually kinda annoying because of its  
size.  You have to search through the entire document to find the  
segment you want.  I suspect a lot of people will decide this is just  
annoying enough that they won't go update an FAQ entry as a result...  
and this is exactly what we want to avoid!

So my gut says a nice index like you've got is terrific, but the  
answers should probably be one-page-per-answer.

You might even be able to get the wiki to make the index for you if  
you put all the FAQ entries in one section or as children to one page  
(the index?) or something...

  Terri