[Freeswitch-users] Some documentation thoughts

[Michael Collins]

I will add this thought to the weekly discussion. Perhaps we can crowdsource
this one.
-MC

On Mon, Oct 12, 2009 at 10:52 PM, Mark Crane <mctch at yahoo.com> wrote:

> "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<http://mc/compose?to=diego.viola@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://mc/compose?to=FreeSWITCH-users@lists.freeswitch.org>
> http://lists.freeswitch.org/mailman/listinfo/freeswitch-users
> UNSUBSCRIBE:http://lists.freeswitch.org/mailman/options/freeswitch-users
> http://www.freeswitch.org
>
>
>
> _______________________________________________
> 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/20091013/7abd4db1/attachment-0002.html