[Freeswitch-users] valet_park timeout

[Michael Collins]

Bob,

I respect your viewpoint. However, nothing you said is new to us. We've
been doing this for over five years. Learning a new software platform is
usually a challenging task. Learning a full-featured soft-switch is even
more daunting. I guarantee that you'd be frustrated by something else, even
if this brand new valet parking timeout feature had already been
documented. That's just the nature of telecom software.

BTW, there is usually a 2-6 week window between when a new feature gets
added to FreeSWITCH and when it gets "properly wikified." The reason for
this is simple - there is a lot involved:
1. Watch git commits regularly
2. Notice new features, tweaks, changes
3. Spend time learning those new changes, including how they might affect
existing features
4. Update a server to the latest git
5. Implement the feature and test test test
6. Update the wiki

The list of people who have both the time and skills to do all of the above
- not to mention the energy and inclination - is quite limited. Usually
what happens is a community member knows a particular subset of FS features
and keeps an eye out for changes and then updates them as soon as he
reasonably can. Also, we have a community conference call each Wednesday
(GMT 1700) wherein we discuss documentation needs, among other things. You
are welcome to join us and talk directly to FS power users and even the
core developers on occasion.

So, in short: we feel your pain. Most of us have felt it at one point or
another as we were all once newbies. We invite you to assist us with easing
the pain of the scores of new users who download FreeSWITCH each day by
helping to improve the wiki. Sign up for a wiki account and I'll get you
confirmed ASAP.

Thanks,
MC

On Fri, Jan 13, 2012 at 3:02 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
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.freeswitch.org/pipermail/freeswitch-users/attachments/20120113/99659bc6/attachment.html