[Freeswitch-docs] better documentation
Hi, It is very difficult to use Freeswitch, because the documentation is very difficult to use. If the documentation was better you would have a lot more users. For example, in https://wiki.freeswitch.org/wiki/Sofia_Configuration_Files , I can read the whole page and I still do not understand fundamental things like: 1) What is a domain? 2) What is a profile? 3) What is a gateway? 4) How is a gateway different than a normal SIP end point? Simple definitions of key ideas and a structured top down descript would help a lot. And there is a lot of useless statements that one has to read through that does not help. For example, "The best thing to do is take a look at these things from a step back." Also it is common to explain what something is not, rather than explaining what it is first. Robert ________________________________ This e-mail and any files transmitted with it may contain privileged or confidential information. It is solely for use by the individual for whom it is intended, even if addressed incorrectly. If you received this e-mail in error, please notify the sender; do not disclose, copy, distribute, or take any action in reliance on the contents of this information; and delete it from your system. Any other use of this e-mail is prohibited. Thank you for your compliance. ________________________________
Robert, Thank you very much for your feedback! This is very valuable for us, and we’ll work on this to make it better for new users. We’re finishing a mass migration from the old wiki, we’re closer, less than 400 pages (we do 100+ per sprint, ~4hours), and after finishing we’ll start polishing pages and re-organizing information. Reach a concise flow in order to learn FreeSWITCH is our goal.
On 13 de jul de 2015, at 12:04, Mundkowsky, Robert <rmundkowsky@ets.org> wrote:
Hi,
It is very difficult to use Freeswitch, because the documentation is very difficult to use.
If the documentation was better you would have a lot more users.
For example, in https://wiki.freeswitch.org/wiki/Sofia_Configuration_Files , I can read the whole page and I still do not understand fundamental things like: 1) What is a domain? 2) What is a profile? 3) What is a gateway? 4) How is a gateway different than a normal SIP end point?
Simple definitions of key ideas and a structured top down descript would help a lot.
And there is a lot of useless statements that one has to read through that does not help. For example, “The best thing to do is take a look at these things from a step back.”
Also it is common to explain what something is not, rather than explaining what it is first.
Robert
This e-mail and any files transmitted with it may contain privileged or confidential information. It is solely for use by the individual for whom it is intended, even if addressed incorrectly. If you received this e-mail in error, please notify the sender; do not disclose, copy, distribute, or take any action in reliance on the contents of this information; and delete it from your system. Any other use of this e-mail is prohibited.
Thank you for your compliance.
_______________________________________________ Freeswitch-docs mailing list Freeswitch-docs@lists.freeswitch.org http://lists.freeswitch.org/mailman/listinfo/freeswitch-docs
Agreed, all the way around. I naively thought it would be a simple project when I first volunteered, but it is a HUGE effort with a huge body of information to organize. We welcome any and all constructive help with this documentation project. Much of the original wiki was by developers writing for developers with a familiar tone. FreeSWITCH is a community project, after all, not a finished package that you buy in a box off a shelf like Progressive insurance so the documentation strives for accuracy if not a polished professional tone. We all contribute the best way we can to improve the overall project. Thanks. --- Bote FreeSWITCH Docs Janitor http://freeswitch.org/confluence
-----Original Message----- From: Ítalo Rossi Sent: Monday, 28 December, 2015 07:16 Subject: Re: [Freeswitch-docs] better documentation
Robert,
Thank you very much for your feedback!
This is very valuable for us, and we’ll work on this to make it better for new users.
We’re finishing a mass migration from the old wiki, we’re closer, less than 400 pages (we do 100+ per sprint, ~4hours), and after finishing we’ll start polishing pages and re-organizing information. Reach a concise flow in order to learn FreeSWITCH is our goal.
On 13 de jul de 2015, at 12:04, Mundkowsky, Robert <rmundkowsky@ets.org> wrote:
Hi,
It is very difficult to use Freeswitch, because the documentation is very difficult to use.
If the documentation was better you would have a lot more users.
For example, in https://wiki.freeswitch.org/wiki/Sofia_Configuration_Files , I can read the whole page and I still do not understand fundamental things like: 1) What is a domain? 2) What is a profile? 3) What is a gateway? 4) How is a gateway different than a normal SIP end point?
Simple definitions of key ideas and a structured top down descript would help a lot.
And there is a lot of useless statements that one has to read through that does not help. For example, “The best thing to do is take a look at these things from a step back.”
Also it is common to explain what something is not, rather than explaining what it is first.
Robert
This e-mail and any files transmitted with it may contain privileged or confidential information. It is solely for use by the individual for whom it is intended, even if addressed incorrectly. If you received this e-mail in error, please notify the sender; do not disclose, copy, distribute, or take any action in reliance on the contents of this information; and delete it from your system. Any other use of this e-mail is prohibited.
Thank you for your compliance.
participants (3)
-
Bote Man
-
Mundkowsky, Robert
-
Ítalo Rossi