[Freeswitch-users] Documentation requests

Wed Oct 3 23:15:49 PDT 2007

Trixter have created a wiki page for the books.

He have also started with some book contents pages. It's an excellent
way to start. All stuff added to the index, by all, might not be
included in the final book, but it will give us a good hint of what we
need to include.

Help us adding sections and with the content order, to make the book
easy to understand.

http://wiki.freeswitch.org/wiki/Newbook

On 10/3/07, Michael Collins <mcollins at fcnetwork.com> wrote:
> Lucia,
>
> Thanks for your input.  Even if it isn't right away, we will work on
> getting this information put into the documentation.  It definitely
> helps to know what, exactly, people would use or need to see in the
> documentation.
>
> -MC
>
> > -----Original Message-----
> > From: freeswitch-users-bounces at lists.freeswitch.org
> [mailto:freeswitch-
> > users-bounces at lists.freeswitch.org] On Behalf Of Lucia Rotger
> > Sent: Wednesday, October 03, 2007 3:15 AM
> > To: freeswitch-users at lists.freeswitch.org
> > Subject: Re: [Freeswitch-users] Documentation requests
> >
> > Hi all,
> >
> > First, I apologize for first asking for documentation and then going
> > silent for three weeks. I am very busy but I hope you find the thoughs
> > below somewhat useful. I believe I cannot help much with them, because
> >
> > - let me first try to put my efforts in context: The documentation
> doesn't
> > need to be foolproof or 'for dummies' but it must be accessible for a
> > reasonably intelligent person. That person is a newbie in VoIP but is
> used
> > to good software (Linux (don't flame me, BSD techies), postgres,
> courier,
> > postfix, samba, ... all those projects have in common that they have
> > fantastic, throughout documentation). They also have a responsive
> > community which I think FS has, or is in the way of having if you
> like.
> >
> > That said I think we need, in the wiki, with high visibility (= main
> > page):
> > - what is voip. I think we all have this one down but still.
> >
> > - putting voip concepts in context (codecs, applications, servers.
> > frameworks). Here is where you put some order in the concepts
> surrounding
> > the technology, and define FS more in depth. They may have a different
> > meaning in another context. For example: things like 'what do you mean
> by
> > 'application' in freeswitch: is it a regular executable run by linux
> > itself, or is it a script run inside freeswitch?' Maybe both ways are
> > supported? Or is this an entirely different thing? That may seem a
> tiny
> > detail but it helps me put things in context (why I think this is
> > important: if the model leans toward 'execute everything inside FS' it
> > means, at least, danger of contention. If then FS talks to databases
> or
> > whatnot, it may extend further and you better be ready to identify
> where
> > will the bottlenecks be coming from under stress; if, on the other
> hand,
> > you lean towards launching processes in the underlying OS and letting
> them
> > run, it means a very different model, IPC (Inter-process
> communication),
> > overhead of launching/tearing down external processes and you get into
> OS
> > issues like file permissions, etc. This is why I like to know).
> Example:
> > Zope, a web framework, is written in Python and can execute Python
> scripts
> > but inside Zope only a subset of Python is available (for security)
> and
> > exception handling and other details are confusing, in fact they
> aren't
> > explained anywhere. Zope is great software and has terrific potential
> but
> > only those very close to its development can use it effectively. Back
> to
> > freeswitch, in regard to script execution, I believe anything that
> > deviates from running a regular, unrestricted javascript script (is
> > javascript the preferred scripting language for freeswitch? I'm not
> sure)
> > must be noted down for anyone to know. Feel free to tell me whether
> I'm
> > making any sense here.
> >
> > Also: What languages are available for scripts? Bindings?
> >
> > - best practices: (We are in beta. Maybe it's too early to define best
> > practices?) in a framework you are free to choose how you do things.
> The
> > devil's in the details and you are left wondering if you are stressing
> it
> > and not benefitting from the 'true' way. I'm out of examples here. Let
> me
> > digress for a moment (again) to Python. In Python you can do things
> like
> > you did in other languages but there's usually a 'Pythonic' way.
> Usually
> > it's more elegant and easier than the old mindset. For example, the
> usual
> > 'iterate over a list and delete items from it' can be done elegantly
> on in
> > a clumsy way because the for clause will skip items if you delete in
> place
> > off the list it's iterating over. Why I'm bringing this over: To a
> newbie
> > (to me at least) best practices are gold because it means I have
> something
> > down and can move over to the next thing. If the developers think
> anything
> > must be done a particular way, please say so, specially if there is
> more
> > than one way to do it and the other ways are bad or inefficient in any
> > respect.
> >
> > - When a page in the wiki is outdated, please make a note saying so
> and
> > explain in what way it's outdated. So someone new to the wiki can at
> least
> > know if the entry is totally outdated or if it only needs small
> updates
> > like listing a new codec. I've seen remarks on the list about a wiki
> page
> > being 'outdated'. It's very easy to go to the wiki and put 'oct 07:
> <your
> > name>: outdated, need to document new behavior in xzzyzzy option'.
> Maybe
> > I'm asking for too much but hey, you wanted feedback. As ESR puts it,
> > asking questions the intelligent way gets them answered half-way, so
> maybe
> > someone seeing that entry can try it and add 'oct 07: <name>: didn't
> work
> > for me, filed bug report number this-and-that'. So now you can go to
> the
> > bug tracker and see the state, without cluttering up the wiki too
> much?
> >
> > - What hardware works with freeswitch. Do you plan to support
> > BRI/PRI/T1/E1 etc cards? Which ones? If so, when? This information
> whould
> > be prominent in the wiki, in the 'what does freeswitch do?' It
> positions
> > FS, and someone evaluating VoIP solutions and skimming through the
> wiki
> > would like to know where FS stands: You are much better suited than me
> for
> > capturing this in a few phrases. Also: Roadmap?
> >
> > - And last but not least, anyone who gets interested (like me) and
> wants
> > more detail must have accessible another crucial thing: the reference.
> > Getting past the generalities and marketing speak (scalable, blah
> blah) we
> > must get down and dirty fast. Make a good reference of every command
> (I
> > know 'command' is probably inadequate because there is more than
> > 'commands' in freeswitch but you get the idea), order it as you like,
> as
> > long as everything is in there. With 'last updated' tags so we know if
> > something has not been touched from 2003, or is recent.
> >
> > As another post said, probably the wiki holds a lot of this already
> but
> > it's sparse and examples don't abound.
> >
> > I'm afraid I just came up with a lot of 'someone should...' items but
> I
> > think those a newbie cannot find out for himself and that's why I'm
> asking
> > for someone else to do them. Also, I tried to reason them a bit. Let
> me
> > know your thoughts?
> > Regards
> > Lucia
> >
> > On Fri, 21 Sep 2007 23:31:09 +0200, Michael Jerris <mike at jerris.com>
> > wrote:
> >
> > > As Anthony had mentioned in another thread, we have heard your
> ongoing
> > > complaints that there is not enough documentation, but we don't know
> > what
> > > kind of documentation you really want.  Please respond to this
> thread
> > > with
> > > what information that you were not able to find on the wiki, that
> would
> > > help
> > > you in using freeswitch.  If no one responds, GREAT!  Were done and
> > don't
> > > need to document anymore.  Otherwise, this is your opportunity to
> speak
> > > up
> > > and say what is missing.
> > >
> > > Mike
> >
> >
> >
> > _______________________________________________
> > 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
>
> _______________________________________________
> 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
>