[Freeswitch-users] valet_park timeout

[Bob Smith]

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