[Freeswitch-users] Some documentation thoughts

[Mark Crane]

"In many cases the issue with the docs isn't that they aren't complete but rather that they are hard to find."

Agreed! The biggest problem with the wiki is that it is hard to find things. 

How do books solve this problem they use an index. It is quite surprising that the wiki software doesn't come with ability to do this basic task automatically and instead relies solely upon a manually created index. It would be extremely beneficial to have a index of all pages and topics that are available on the wiki. The average person may only see the main links in the documentation and not realize there are actually hundreds of pages.

There used to be a pdf that was auto generated from the wiki and it gave a much easier view of all the pages on the wiki.

Mark J Crane



--- On Mon, 10/12/09, Michael Collins <msc at freeswitch.org> wrote:

From: Michael Collins <msc at freeswitch.org>
Subject: Re: [Freeswitch-users] Some documentation thoughts
To: freeswitch-users at lists.freeswitch.org
Date: Monday, October 12, 2009, 4:38 PM


On Mon, Oct 12, 2009 at 3:11 PM, Diego Viola <diego.viola at gmail.com> wrote:

Hello,

I have been doing some work recently on the FreeSWITCH wiki, to improve things.

You can see some of my work here:

http://wiki.freeswitch.org/index.php?title=Special:Contributions&limit=500&target=Diego.viola



I am trying to polish the wiki and give it a more professional and clean look, this means that we need to enforce some guidelines and strive to make the wiki even better.

How can we do this?

Well, the first thing is to review everything we have, right now we have too many separated and little pages here and there that no one cares or read, we should avoid doing little or small pages. We need to correct typos, I suggest that people click on "Random page" link and start correcting typos, install an English (US) dictionary in your browser and enable Spell Checking and start correcting these typos if you want to help, also, make acronyms and initialisms all-uppercase when you make one.



When you are adding documentation make sure you don't do a separate page for an existing page, etc. and we also need to define a size for titles, body, etc, so different pages don't look different from each other, I will make sure I add all this into our guidelines and that all pages follow this.



My goal is to have great documentation, similar to the Apache documentation:
http://httpd.apache.org/docs/2.2/

Or even better, I hope you like this idea.


Diego,

Thank you so much for all of your help on this. Many in the community have seen your work - it has not gone unnoticed and it most truly is appreciated. I like the idea of improving the documentation. One thing we need to do is re-think the organization. In many cases the issue with the docs isn't that they aren't complete, but rather that they are hard to find. It's all about organization. I'm definitely open to ideas.


For those who are interested in helping out with the wiki please let me know of your availability and skill set. I am maintaining a list of volunteers.

Lastly, if you want to talk about documentation in real time please join us in #freeswitch-docs.


Thanks,
MC



-----Inline Attachment Follows-----

_______________________________________________
FreeSWITCH-users mailing list
FreeSWITCH-users at lists.freeswitch.org
http://lists.freeswitch.org/mailman/listinfo/freeswitch-users
UNSUBSCRIBE:http://lists.freeswitch.org/mailman/options/freeswitch-users
http://www.freeswitch.org



      
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.freeswitch.org/pipermail/freeswitch-users/attachments/20091012/5fb7bf41/attachment-0002.html