[Freeswitch-users] valet_park timeout

[Brian Foster]

The problem is this: if developers had to write out documentation for every
feature/variable/trick/etc. they came up with, they wouldn't have time to
maintain the software (which of course is free, open source, etc.) Keep in
mind that you don't need to be a developer to write documentation. The best
thing to do is if something is undocumented, ask. Then, turn around and
wikify it. I wholeheartedly believe that this project does quite well with
documentation. There has been extensive work done by many to keep up with
the new features/variables/tricks/etc. We have and always will have room to
grow.

Anyway, that's my 2¢. Take it or leave it.

-BD
On Jan 13, 2012 6:04 PM, "Bob Smith" <gb10hkzo-freeswitch at yahoo.co.uk>
wrote:

> Michael,
>
>
> Permit me to perhaps expand a little on why I said what I did :
>
>
> 1. As a newbie to Freeswitch, it is right and proper that I take the time
> to review the available documentation (including purchasing the eBook in my
> case).  The wiki documentation is severely lacking... some of it is out of
> date, a lot of it is very sparse, and there many un-necessary and
> unprofessional comments embedded in it (e.g. "???What is it
> acknowledging???", "What does this do ???" etc.).  I have been spending
> many frustrating hours trying to educate myself in the mysterious
> FreeSwitch through the wiki and eBooks.  Why ? Because I consider it the
> correct approach as opposed to littering the "freeswitch-users" list with a
> ton of newbie questions.
>
>
> 2. Building on the point above, surely you should be encouraging ease of
> adoption by a new community of users.  Uses who will no doubt eventually
> end up contributing to the project as their experience with Freeswitch
> grows, and their time permits.  It is not exactly fair or reasonable to
> expect newbies to dig around the source code in order to uncover useful
> functions which are undocumented, but have long been stable.  Particularly,
> if like me, their background is not in C programming.
>
>
> 3. I was not asking the developers to write a book each time they code a
> new feature.  Even just a two column table (function/variable/etc + one or
> two phrase description of function/variable/etc.) would be better than the
> old, out of date Wiki of today.   The developers are the ones best placed
> to know when a feature is (a) introduced and (b) becomes stable enough in
> the code tree that they are happy with it.  As you well know, half of a
> coders job is documenting .... uncommented code is sloppy, undocumented
> software is unusable.   As developers, you should be proud of your work,
> proud of all the new features you're introducing, and the existing features
> you are enhancing.  So surely you should be blowing your trumpet by even
> modestly documenting your new work by a new phrase or two in the wiki ?
>
>
> Take my example of valet_park timeouts …. I spent much time trying to
> search through the lists, more time digging fruitlessly through the wiki
> and the eBook in search of the faintest trace of documentation of the new
> variables introduced.  I tried poking through the source code, but being
> unfamiliar with (a) C and (b) the FreeSwitch tree, I couldn't really
> comprehend what was going on.  So I ask on Freeswitch-Users and get a
> stupid answer that says "LOOK CLOSELY" (little did the poster know just how
> much time I had expended "looking closely" !!!)  … I spent days looking
> closely, days which could have been avoided if the developers took 2
> minutes to add 4 lines to the Wiki just listing and ever so briefly
> describing the new variables !
>
>
> Everyone is entitled to their own opinion, of course, but I suspect this
> is one area where ours may vary !
>
>
> B
>
> _________________________________________________________________________
> Professional FreeSWITCH Consulting Services:
> consulting at freeswitch.org
> http://www.freeswitchsolutions.com
>
> 
> 
>
> Official FreeSWITCH Sites
> http://www.freeswitch.org
> http://wiki.freeswitch.org
> http://www.cluecon.com
>
> 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/20120113/e7dc4cab/attachment-0001.html