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
First let me say. After spending a significant amount of time debugging using gdb I can safely say this project is well engineered and the development team is top notch. Thank you for everything you have done. After much debugging and work, I am attempting to solve and document the issue of using multiple SIP lines for inbound and outbound calls with the same or different carriers. The information would need to show and explain an example using sofia.conf.xml, the XML dial plan bridging of a call and a corresponding JavaScript example. Perhaps I am the only one having this issue, but it would be nice to see examples with explanations of this within the wiki. Assuming I can finally solve my issue, I shall add the information myself. I realize that some of these facts are added already into the wiki, but the truth is that they are disconnected, contain minuscule amounts of information and make it hard for a FreeSwitch newbie such as myself to get my show up and running. Regards, Chris
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
Chris, Make sure you stop by IRC and ask questions we'll answer them! :) /b On Sep 21, 2007, at 4:53 PM, Chris Danielson wrote:
First let me say. After spending a significant amount of time debugging using gdb I can safely say this project is well engineered and the development team is top notch. Thank you for everything you have done.
After much debugging and work, I am attempting to solve and document the issue of using multiple SIP lines for inbound and outbound calls with the same or different carriers. The information would need to show and explain an example using sofia.conf.xml, the XML dial plan bridging of a call and a corresponding JavaScript example. Perhaps I am the only one having this issue, but it would be nice to see examples with explanations of this within the wiki. Assuming I can finally solve my issue, I shall add the information myself. I realize that some of these facts are added already into the wiki, but the truth is that they are disconnected, contain minuscule amounts of information and make it hard for a FreeSwitch newbie such as myself to get my show up and running.
Regards, Chris
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@lists.freeswitch.org http://lists.freeswitch.org/mailman/listinfo/freeswitch-users UNSUBSCRIBE:http://lists.freeswitch.org/mailman/options/freeswitch- users http://www.freeswitch.org
If you want. I can translate some docs to spanish. Regards, Santiago Date: Fri, 21 Sep 2007 17:31:09 -0400From: mike@jerris.comTo: freeswitch-users@lists.freeswitch.orgSubject: [Freeswitch-users] Documentation requestsAs 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 _________________________________________________________________ Descubre Live.com - tu propia página de inicio, personalizada para ver rápidamente todo lo que te interesa en un mismo sitio. http://www.live.com/getstarted
On 9/21/07, Santiago Gimenez Ocano <sxntixgo@hotmail.com> wrote:
If you want. I can translate some docs to spanish.
That would be appreciated, perhaps we can get a language module for the wiki site, either that or some sort of mirror of the content that can coexist in multiple languages. I am not familiar with any of the features of the wiki other than as a user, so I dont know what exists and how difficult it would be, but there has to be some solution to do that. bkw or xachen would be the ones to talk to about the wiki software as they are more familiar with it. It would be great ot have it translated into multiple languages, and I can make the pdf generation create language specific PDFs of the different languages for people that need/want offline reading. -- Trixter http://www.0xdecafbad.com Bret McDanel Belfast +44 28 9099 6461 US +1 516 687 5200 http://www.trxtel.com the phone company that pays you!
I am not familiar with wiki software, but I know how to write Latex. I have read that wikipedia uses a similar languaje Regards, Santiago Date: Sat, 22 Sep 2007 00:20:58 +0200From: trixter@0xdecafbad.comTo: freeswitch-users@lists.freeswitch.orgSubject: Re: [Freeswitch-users] Documentation requests On 9/21/07, Santiago Gimenez Ocano <sxntixgo@hotmail.com> wrote: If you want. I can translate some docs to spanish. That would be appreciated, perhaps we can get a language module for the wiki site, either that or some sort of mirror of the content that can coexist in multiple languages. I am not familiar with any of the features of the wiki other than as a user, so I dont know what exists and how difficult it would be, but there has to be some solution to do that. bkw or xachen would be the ones to talk to about the wiki software as they are more familiar with it.It would be great ot have it translated into multiple languages, and I can make the pdf generation create language specific PDFs of the different languages for people that need/want offline reading. -- Trixter http://www.0xdecafbad.com Bret McDanelBelfast +44 28 9099 6461 US +1 516 687 5200http://www.trxtel.com the phone company that pays you! _________________________________________________________________ Descubre Live.com - tu propia página de inicio, personalizada para ver rápidamente todo lo que te interesa en un mismo sitio. http://www.live.com/getstarted
I just added Broadvoice to this page: http://wiki.freeswitch.org/wiki/SIP_Provider_Examples On 9/21/07, Santiago Gimenez Ocano <sxntixgo@hotmail.com> wrote:
I am not familiar with wiki software, but I know how to write Latex. I have read that wikipedia uses a similar languaje
Regards, Santiago
________________________________ Date: Sat, 22 Sep 2007 00:20:58 +0200 From: trixter@0xdecafbad.com To: freeswitch-users@lists.freeswitch.org Subject: Re: [Freeswitch-users] Documentation requests
On 9/21/07, Santiago Gimenez Ocano <sxntixgo@hotmail.com> wrote:
If you want. I can translate some docs to spanish.
That would be appreciated, perhaps we can get a language module for the wiki site, either that or some sort of mirror of the content that can coexist in multiple languages. I am not familiar with any of the features of the wiki other than as a user, so I dont know what exists and how difficult it would be, but there has to be some solution to do that.
bkw or xachen would be the ones to talk to about the wiki software as they are more familiar with it.
It would be great ot have it translated into multiple languages, and I can make the pdf generation create language specific PDFs of the different languages for people that need/want offline reading.
-- Trixter http://www.0xdecafbad.com Bret McDanel Belfast +44 28 9099 6461 US +1 516 687 5200 http://www.trxtel.com the phone company that pays you! ________________________________ Envía mensajes de correo electrónico directamente a tu blog con MSN. Carga chistes, fotografías y muchas otras cosas. Es gratis. _______________________________________________ Freeswitch-users mailing list 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
I have actually wanted to switch to doing a docbook repo and just generate the docs from that. Is anyone up for that task? It will be a huge task! /b On Sep 21, 2007, at 5:28 PM, Santiago Gimenez Ocano wrote:
I am not familiar with wiki software, but I know how to write Latex. I have read that wikipedia uses a similar languaje
Regards, Santiago
Date: Sat, 22 Sep 2007 00:20:58 +0200 From: trixter@0xdecafbad.com To: freeswitch-users@lists.freeswitch.org Subject: Re: [Freeswitch-users] Documentation requests
On 9/21/07, Santiago Gimenez Ocano <sxntixgo@hotmail.com> wrote:
If you want. I can translate some docs to spanish.
That would be appreciated, perhaps we can get a language module for the wiki site, either that or some sort of mirror of the content that can coexist in multiple languages. I am not familiar with any of the features of the wiki other than as a user, so I dont know what exists and how difficult it would be, but there has to be some solution to do that.
bkw or xachen would be the ones to talk to about the wiki software as they are more familiar with it.
It would be great ot have it translated into multiple languages, and I can make the pdf generation create language specific PDFs of the different languages for people that need/want offline reading.
-- Trixter http://www.0xdecafbad.com Bret McDanel Belfast +44 28 9099 6461 US +1 516 687 5200 http://www.trxtel.com the phone company that pays you!
Envía mensajes de correo electrónico directamente a tu blog con MSN. Carga chistes, fotografías y muchas otras cosas. Es gratis. _______________________________________________ Freeswitch-users mailing list 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
On 9/22/07, Brian West <brian.west@mac.com> wrote:
I have actually wanted to switch to doing a docbook repo and just generate the docs from that. Is anyone up for that task? It will be a huge task!
Why didnt we use docbook from the start? What advantages does docbook give us that we dont have now? Basically why spend the effort switching? And the task may not be as huge as you think, remember I do go through every wiki page, parse it, blah blah blah then make a pdf out of the resulting information. Instead of formatting it the way I do for the pdf I can possibly format it in a docbook capable way, maybe even automate the posting. -- Trixter http://www.0xdecafbad.com Bret McDanel Belfast +44 28 9099 6461 US +1 516 687 5200 http://www.trxtel.com the phone company that pays you!
Can we try to keep this thread focused on what kind of documentation people need, not the format we can store it in please. On 9/22/07, Trixter aka Bret McDanel <trixter@0xdecafbad.com> wrote:
On 9/22/07, Brian West <brian.west@mac.com> wrote:
I have actually wanted to switch to doing a docbook repo and just generate the docs from that. Is anyone up for that task? It will be a huge task!
Why didnt we use docbook from the start? What advantages does docbook give us that we dont have now? Basically why spend the effort switching?
And the task may not be as huge as you think, remember I do go through every wiki page, parse it, blah blah blah then make a pdf out of the resulting information. Instead of formatting it the way I do for the pdf I can possibly format it in a docbook capable way, maybe even automate the posting.
-- Trixter http://www.0xdecafbad.com Bret McDanel Belfast +44 28 9099 6461 US +1 516 687 5200 http://www.trxtel.com the phone company that pays you!
_______________________________________________ Freeswitch-users mailing list 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
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@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
A typical bossy troll-gear commanding request and yea I have heard loudly enough. Let me tell you that you are asking too much from the FS developers in particular and to the FS community in general. To begin with, get the FS source code and start reading it line by line and do some coding with emphasis on attention-to-details afterwards some thorough practical experimentation with it. IMHO, advocate a fund raising campaign for your wishlists as well as convince O'reilly and maybe your employer to sponsor a book funding for this project. You should remember that the only thing left free in this world is the air that we breath and the rest, you ought to pay for the time and effort of someone. Gone are the days when some geeks in a basement darkroom has to write a code of something that will benefit all humankind(excluding the terrorist bcoz they are not humans after all rofl ) and distribute it out to the end corners of the universe for free because it was for fun then guys like you and me will just use it right away for our business purposes.
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@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@lists.freeswitch.org http://lists.freeswitch.org/mailman/listinfo/freeswitch-users UNSUBSCRIBE:http://lists.freeswitch.org/mailman/options/freeswitch-users http://www.freeswitch.org
On 10/3/07, demuel@thephinix.org <demuel@thephinix.org> wrote:
A typical bossy troll-gear commanding request and yea I have heard loudly enough. Let me tell you that you are asking too much from the FS developers in particular and to the FS
There had been plans to do much of that for about 2 years. I dont think that the request is asking for too much, only that there hasnt been enough time to do it yet. community in general. To begin with, get the FS source code and start
reading it line by line and do some coding with emphasis on attention-to-details afterwards some thorough
As for saying 'get the source and read it' that may not be the best response since not all users are developers. As a community I would like to think that we are open and available to both users and developers. practical experimentation with it. IMHO, advocate a fund raising campaign
for your wishlists as well as convince O'reilly and maybe your employer to sponsor a book funding for this project. You should remember that the only thing left free in this world is the
The comment about a fund raiser I am fairly sure would help, I know I personally would do more than just some of the initial planning towards more and better documentation since I would be able to turn down some paying work to actually have time. There are likely others as well that would feel that way. air that we breath and the rest, you ought to pay for the time and effort of
someone. Gone are the days when some geeks in a basement darkroom has to write a code of something that will benefit all humankind(excluding the terrorist bcoz they are not humans after all rofl ) and distribute it out to the end corners of the universe for free because it was for fun then guys like you and me will just use it right away for our business purposes.
That isnt quite true, simply because you can get software, and you can use it for business purposes. Infact FreeSWITCH[tm] has intentionally made the choice to more readily allow that. -- Trixter http://www.0xdecafbad.com Bret McDanel Belfast +44 28 9099 6461 US +1 516 687 5200 http://www.trxtel.com the phone company that pays you!
On Oct 3, 2007, at 9:24 AM, Lucia Rotger wrote:
On Wed, 03 Oct 2007 12:49:31 +0200, <demuel@thephinix.org> wrote:
A typical bossy troll-gear...
Your point? Seeing as I see that your contribution to this list as far as archives go is exactly zero this is all the answer you are going to get from me. Troll.
Lucia
I'm going to put an end to this right now. Troll calling and such will not be tolerated. Everyone here is free to voice their opinion but lets not name call or do this. Its counter productive. The best corse of action is to move forward and use the energy to write docs or proof the already existing docs. You two shake hands and be civil please. Thanks, /b
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@lists.freeswitch.org [mailto:freeswitch- users-bounces@lists.freeswitch.org] On Behalf Of Lucia Rotger Sent: Wednesday, October 03, 2007 3:15 AM To: freeswitch-users@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@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@lists.freeswitch.org http://lists.freeswitch.org/mailman/listinfo/freeswitch-users
UNSUBSCRIBE:http://lists.freeswitch.org/mailman/options/freeswitch-users
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@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@lists.freeswitch.org [mailto:freeswitch- users-bounces@lists.freeswitch.org] On Behalf Of Lucia Rotger Sent: Wednesday, October 03, 2007 3:15 AM To: freeswitch-users@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@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@lists.freeswitch.org http://lists.freeswitch.org/mailman/listinfo/freeswitch-users
UNSUBSCRIBE:http://lists.freeswitch.org/mailman/options/freeswitch-users
_______________________________________________ Freeswitch-users mailing list 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
Trixter have created a wiki page for the books.
Yes, it's in its infancy, so don't be worried if it seems skeletally thin.
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.
FYI, please don't start doing copy & paste operations and dump unchecked or unverified information into the new book. The idea is that any information put into the new book is high quality, proof-read, and accurate. Please check and re-check any information you intend to put into the new book. -MC
On 10/4/07, Michael Collins <mcollins@fcnetwork.com> wrote:
FYI, please don't start doing copy & paste operations and dump unchecked or unverified information into the new book. The idea is that any information put into the new book is high quality, proof-read, and accurate. Please check and re-check any information you intend to put into the new book.
Just to be clear, the premise for that is so that we dont end up with what we currently have, something many have complained about. By writing content for the book, rather than creating a book from existing content the hope is to get higher quality documentation. As of yesterday the users guide has the most work done on it, which admittedly isnt much, but I just did that yesterday and was still trying to get things like a style guide done, and a list of what content needs to be written. -- Trixter http://www.0xdecafbad.com Bret McDanel Belfast +44 28 9099 6461 US +1 516 687 5200 http://www.trxtel.com the phone company that pays you!
participants (10)
-
Brian West
-
Chris Danielson
-
demuel＠thephinix.org
-
Jason Garland
-
Jonas Gauffin
-
Lucia Rotger
-
Michael Collins
-
Michael Jerris
-
Santiago Gimenez Ocano
-
Trixter aka Bret McDanel