[Mailman-Developers] Documentation status?

[Jason Pruim]

On Mar 11, 2008, at 10:59 PM, Terri Oda wrote:

> On 11-Mar-08, at 11:00 AM, Jason Pruim wrote:
>
> 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)
>

Yeah, I see the issue with that, always scrolling back up to the top  
to see the index might be a bit of a pain... I'll probably download  
the text of the questions/answers to my computer this weekend so I can  
work on organizing them without screwing up what is already there :)

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

One page per answer, with links to the previous/next questions as well  
as the index? So for the people who are reading each one, they would  
be able to flip between them without going back and then picking the  
next one...

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

I'll play with the wiki, Maybe make a page just to play with... I  
don't have a TON of experience with wiki's, but I know the basics, If  
I do make a page just for testing can I transfer that to a different  
page after it's formatted correctly?



--

Jason Pruim
Raoset Inc.
Technology Manager
MQC Specialist
3251 132nd ave
Holland, MI, 49424-9337
www.raoset.com
japruim at raoset.com