Re: [Freeswitch-users] Should I choose FreeSwitch?
Ha, Too bad all the text going back and forth in this thread was not actual documentation instead of deliberations about documentation practices or we'd be done already =D Anyone who want's to do anything to help the documentation effort by my guest to make any wiki page etc you need. I don't see a mad rush of volunteers so I won't hold my breath or anything but if I run out of bugs to fix and code to write I will start working on this myself..... Anthony Minessale II FreeSWITCH http://www.freeswitch.org/ ClueCon http://www.cluecon.com/ AIM: anthm MSN:anthony_minessale@hotmail.com GTALK/JABBER/PAYPAL:anthony.minessale@gmail.com IRC: irc.freenode.net #freeswitch FreeSWITCH Developer Conference sip:888@conference.freeswitch.org iax:guest@conference.freeswitch.org/888 googletalk:conf+888@conference.freeswitch.org pstn:213-799-1400 ----- Original Message ---- From: Jonas Gauffin <jonas.gauffin@gmail.com> To: freeswitch-users@lists.freeswitch.org Sent: Thursday, September 20, 2007 8:47:15 AM Subject: Re: [Freeswitch-users] Should I choose FreeSwitch? I'm not talking about if people can or can't edit the pages. I'm talking about users that want to find or read documentation (not contribute). For instance: New users. They want to find documentation and read it. Those users can give valuable feedback to us (so that we can make the documentation better) if they do not understand it / think that some documentation is missing. What I want is a way for those users to give us that feedback. They can, as you say, edit the pages and add their questions / suggestions directly in the page. But what will a page look like if 20 users have added questions / suggestions for improvement on it? Again: I'm not talking about user who can contribute with information (having know-how), but about new users who want to use/configure FreeSwitch (like new users). There are a section on the first page called "Community and Support" on the first page which tells the user how to get help. Maybe there should also be a section called "How to give feedback" too? On 9/20/07, Trixter aka Bret McDanel <trixter@0xdecafbad.com> wrote:
On 9/20/07, Jonas Gauffin <jonas.gauffin@gmail.com> wrote:
Ahh.. My mistake. I searched for both "FAQ" and "Frequently asked questions" without getting a hit.
The searching on that site is admittedly a bit weak, I do not know what to do about that, nor do I have any control over that since its the people that have direct control of the site. I will talk to someone and see if there is anything they can do in that regard.
Then I saw this in the documentation guidelines: "Try to avoid FAQs". My conclusion was therefore that it was removed. But I found it now =)
The 'try to avoid faqs' in the guidelines refers to documenting a module or something else. If you were to document mod_something there shouldnt be a need for a FAQ about that module, since the documentation should explain what it does and how to use it. If you feel the need for a FAQ on mod_something then perhaps the documentation itself should be extended to answer those questions. :)
My point was that people who can't contribute with information should be able to REQUEST information. Those requests shouldn't be added in the documentation, but in the Talk pages or special request pages
I dont understand, they have to edit a wiki page to request information or add to the talk section, but they cant edit a different wiki page to actually create documentation? Almost seems like its an extra layer of stuff that people would have to actively seek out to read and then update the documentation just to create this process.
Why cant people contribute to the documentation effort but could contribute to wiki pages on the same system?
I created the documentation guidelines page too :) But that's for ppl that can actually contribute in the documentation. Not for ppl that as missing or not understanding some documentation.
everyone can contribute, you make it sound like only some people are allowed and others cant. Maybe that is my misunderstanding when you constantly refer to people who cant edit documentation but can edit some other page on the wiki.
I just dont understand why this extra layer is a good thing, if people can add to those pages they can add to the documentation itself. There is a list of missing documents, which I periodically update, as well as a list of empty pages which I update at the same time. If someone were to link to a page that doesnt exist, during the generation of the PDF I would see that and be able to edit that list, thus forming a 'weak spot in the documentation' list, which currently is there, on the main documentation page.
-- 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
_______________________________________________ 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 ____________________________________________________________________________________ Don't let your dream ride pass you by. Make it a reality with Yahoo! Autos. http://autos.yahoo.com/index.html
Anthm is right - the best source for documentation is users who know how to write about their experiences. Brian made a good point: he sucks at writing documentation but he's more than willing to read documentation prepared by members of the community. Anthm and Brian are also very good about answering questions, so if you've got an idea for a document and aren't sure about the specifics you can always ask the coders for guidance. Believe me, those hacking the code will be eternally grateful to those who hack the documentation. Even if all you do is get something started and then ask for guidance then that would be great. Programmers generally hate writing documentation, and one reason is the so-call "blank page effect." Trixter has shown that he's willing to work diligently on this as well. There is no shortage of brain power for greasing the wheels that produce the documentation. However, the community is better served by having that brain power focused on the product itself, not the documentation of the product. Don't forget one of the great quotes of our time: "Documentation is like sex: when it's good, it's really good, and when it's bad, it's better than nothing." If people really want documentation but are unwilling/unable to produce it themselves, perhaps they'd be willing to pony up a few bucks for a documentation bounty? If every person who wished for better/more documentation offered $5 or $10 to put into the pot then we'd quickly have a nice new incentive for some of the power users to step up and hammer out some professional-level documentation. (Personally, I'd be willing to seed the pot with $25 or so.) Just a thought. -MC P.S. - as much as this thread feels like a waste, it isn't. When a FOSS project gets to the point where people are clamoring for documentation, and doing so passionately, then it's a sign that the project has arrived. Congrats to Anthony, Brian, and the rest of the community. You've come a long way from the days where the FS main page had a little cave man hammering on is stone wheel! _____ From: freeswitch-users-bounces@lists.freeswitch.org [mailto:freeswitch-users-bounces@lists.freeswitch.org] On Behalf Of Anthony Minessale Sent: Friday, September 21, 2007 11:24 AM To: freeswitch-users@lists.freeswitch.org Subject: Re: [Freeswitch-users] Should I choose FreeSwitch? Ha, Too bad all the text going back and forth in this thread was not actual documentation instead of deliberations about documentation practices or we'd be done already =D Anyone who want's to do anything to help the documentation effort by my guest to make any wiki page etc you need. I don't see a mad rush of volunteers so I won't hold my breath or anything but if I run out of bugs to fix and code to write I will start working on this myself..... Anthony Minessale II FreeSWITCH http://www.freeswitch.org/ ClueCon http://www.cluecon.com/ AIM: anthm MSN:anthony_minessale@hotmail.com GTALK/JABBER/PAYPAL:anthony.minessale@gmail.com IRC: irc.freenode.net #freeswitch FreeSWITCH Developer Conference sip:888@conference.freeswitch.org iax:guest@conference.freeswitch.org/888 googletalk:conf+888@conference.freeswitch.org pstn:213-799-1400 ----- Original Message ---- From: Jonas Gauffin <jonas.gauffin@gmail.com> To: freeswitch-users@lists.freeswitch.org Sent: Thursday, September 20, 2007 8:47:15 AM Subject: Re: [Freeswitch-users] Should I choose FreeSwitch? I'm not talking about if people can or can't edit the pages. I'm talking about users that want to find or read documentation (not contribute). For instance: New users. They want to find documentation and read it. Those users can give valuable feedback to us (so that we can make the documentation better) if they do not understand it / think that some documentation is missing. What I want is a way for those users to give us that feedback. They can, as you say, edit the pages and add their questions / suggestions directly in the page. But what will a page look like if 20 users have added questions / suggestions for improvement on it? Again: I'm not talking about user who can contribute with information (having know-how), but about new users who want to use/configure FreeSwitch (like new users). There are a section on the first page called "Community and Support" on the first page which tells the user how to get help. Maybe there should also be a section called "How to give feedback" too? On 9/20/07, Trixter aka Bret McDanel <trixter@0xdecafbad.com> wrote:
On 9/20/07, Jonas Gauffin <jonas.gauffin@gmail.com> wrote:
Ahh.. My mistake. I searched for both "FAQ" and "Frequently asked questions" without getting a hit.
The searching on that site is admittedly a bit weak, I do not know what to do about that, nor do I have any control over that since its the people that have direct control of the site. I will talk to someone and see if there is anything they can do in that regard.
Then I saw this in the documentation guidelines: "Try to avoid FAQs". My conclusion was therefore that it was removed. But I found it now =)
The 'try to avoid faqs' in the guidelines refers to documenting a module or something else. If you were to document mod_something there shouldnt be a need for a FAQ about that module, since the documentation should explain what it does and how to use it. If you feel the need for a FAQ on mod_something then perhaps the documentation itself should be extended to answer those questions. :)
My point was that people who can't contribute with information should be able to REQUEST information. Those requests shouldn't be added in the documentation, but in the Talk pages or special request pages
I dont understand, they have to edit a wiki page to request information or add to the talk section, but they cant edit a different wiki page to actually create documentation? Almost seems like its an extra layer of stuff that people would have to actively seek out to read and then update the documentation just to create this process.
Why cant people contribute to the documentation effort but could contribute to wiki pages on the same system?
I created the documentation guidelines page too :) But that's for
ppl
that can actually contribute in the documentation. Not for ppl that as missing or not understanding some documentation.
everyone can contribute, you make it sound like only some people are allowed and others cant. Maybe that is my misunderstanding when you constantly refer to people who cant edit documentation but can edit some other page on the wiki.
I just dont understand why this extra layer is a good thing, if people can add to those pages they can add to the documentation itself. There is a list of missing documents, which I periodically update, as well as a list of empty pages which I update at the same time. If someone were to link to a page that doesnt exist, during the generation of the PDF I would see that and be able to edit that list, thus forming a 'weak spot in the documentation' list, which currently is there, on the main documentation page.
-- 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
_______________________________________________ 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 _____ Be a better Globetrotter. Get <http://us.rd.yahoo.com/evt=48254/*http:/answers.yahoo.com/dir/_ylc=X3oD MTI5MGx2aThyBF9TAzIxMTU1MDAzNTIEX3MDMzk2NTQ1MTAzBHNlYwNCQUJwaWxsYXJfTklf MzYwBHNsawNQcm9kdWN0X3F1ZXN0aW9uX3BhZ2U-?link=list&sid=396545469> better travel answers from someone who knows. Yahoo! Answers - Check it out.
How about documentation bounties? Something like $5 - $10 each. ;) On 9/21/07, Michael Collins <mcollins@fcnetwork.com> wrote:
Anthm is right – the best source for documentation is users who know how to write about their experiences. Brian made a good point: he sucks at writing documentation but he's more than willing to read documentation prepared by members of the community. Anthm and Brian are also very good about answering questions, so if you've got an idea for a document and aren't sure about the specifics you can always ask the coders for guidance. Believe me, those hacking the code will be eternally grateful to those who hack the documentation. Even if all you do is get something started and then ask for guidance then that would be great. Programmers generally hate writing documentation, and one reason is the so-call "blank page effect."
Trixter has shown that he's willing to work diligently on this as well. There is no shortage of brain power for greasing the wheels that produce the documentation. However, the community is better served by having that brain power focused on the product itself, not the documentation of the product.
Don't forget one of the great quotes of our time: "Documentation is like sex: when it's good, it's really good, and when it's bad, it's better than nothing."
If people really want documentation but are unwilling/unable to produce it themselves, perhaps they'd be willing to pony up a few bucks for a documentation bounty? If every person who wished for better/more documentation offered $5 or $10 to put into the pot then we'd quickly have a nice new incentive for some of the power users to step up and hammer out some professional-level documentation. (Personally, I'd be willing to seed the pot with $25 or so.)
Just a thought.
-MC
P.S. – as much as this thread feels like a waste, it isn't. When a FOSS project gets to the point where people are clamoring for documentation, and doing so passionately, then it's a sign that the project has arrived. Congrats to Anthony, Brian, and the rest of the community. You've come a long way from the days where the FS main page had a little cave man hammering on is stone wheel!
________________________________
From: freeswitch-users-bounces@lists.freeswitch.org [mailto:freeswitch-users-bounces@lists.freeswitch.org] On Behalf Of Anthony Minessale Sent: Friday, September 21, 2007 11:24 AM To: freeswitch-users@lists.freeswitch.org Subject: Re: [Freeswitch-users] Should I choose FreeSwitch?
Ha,
Too bad all the text going back and forth in this thread was not actual documentation instead of deliberations about documentation practices or we'd be done already =D
Anyone who want's to do anything to help the documentation effort by my guest to make any wiki page etc you need. I don't see a mad rush of volunteers so I won't hold my breath or anything but if I run out of bugs to fix and code to write I will start working on this myself.....
Anthony Minessale II
FreeSWITCH http://www.freeswitch.org/ ClueCon http://www.cluecon.com/
AIM: anthm MSN:anthony_minessale@hotmail.com GTALK/JABBER/PAYPAL:anthony.minessale@gmail.com IRC: irc.freenode.net #freeswitch
FreeSWITCH Developer Conference sip:888@conference.freeswitch.org iax:guest@conference.freeswitch.org/888 googletalk:conf+888@conference.freeswitch.org pstn:213-799-1400
----- Original Message ---- From: Jonas Gauffin <jonas.gauffin@gmail.com> To: freeswitch-users@lists.freeswitch.org Sent: Thursday, September 20, 2007 8:47:15 AM Subject: Re: [Freeswitch-users] Should I choose FreeSwitch?
I'm not talking about if people can or can't edit the pages.
I'm talking about users that want to find or read documentation (not contribute). For instance: New users.
They want to find documentation and read it. Those users can give valuable feedback to us (so that we can make the documentation better) if they do not understand it / think that some documentation is missing.
What I want is a way for those users to give us that feedback. They can, as you say, edit the pages and add their questions / suggestions directly in the page. But what will a page look like if 20 users have added questions / suggestions for improvement on it?
Again: I'm not talking about user who can contribute with information (having know-how), but about new users who want to use/configure FreeSwitch (like new users).
There are a section on the first page called "Community and Support" on the first page which tells the user how to get help. Maybe there should also be a section called "How to give feedback" too?
On 9/20/07, Trixter aka Bret McDanel <trixter@0xdecafbad.com> wrote:
On 9/20/07, Jonas Gauffin <jonas.gauffin@gmail.com> wrote:
Ahh.. My mistake. I searched for both "FAQ" and "Frequently asked questions" without getting a hit.
The searching on that site is admittedly a bit weak, I do not know what to do about that, nor do I have any control over that since its the people that have direct control of the site. I will talk to someone and see if there is anything they can do in that regard.
Then I saw this in the documentation guidelines: "Try to avoid FAQs". My conclusion was therefore that it was removed. But I found it now =)
The 'try to avoid faqs' in the guidelines refers to documenting a module or something else. If you were to document mod_something there shouldnt be a need for a FAQ about that module, since the documentation should explain what it does and how to use it. If you feel the need for a FAQ on mod_something then perhaps the documentation itself should be extended to answer those questions. :)
My point was that people who can't contribute with information should be able to REQUEST information. Those requests shouldn't be added in the documentation, but in the Talk pages or special request pages
I dont understand, they have to edit a wiki page to request information or add to the talk section, but they cant edit a different wiki page to actually create documentation? Almost seems like its an extra layer of stuff that people would have to actively seek out to read and then update the documentation just to create this process.
Why cant people contribute to the documentation effort but could contribute to wiki pages on the same system?
I created the documentation guidelines page too :) But that's for ppl that can actually contribute in the documentation. Not for ppl that as missing or not understanding some documentation.
everyone can contribute, you make it sound like only some people are allowed and others cant. Maybe that is my misunderstanding when you constantly refer to people who cant edit documentation but can edit some other page on the wiki.
I just dont understand why this extra layer is a good thing, if people can add to those pages they can add to the documentation itself. There is a list of missing documents, which I periodically update, as well as a list of empty pages which I update at the same time. If someone were to link to a page that doesnt exist, during the generation of the PDF I would see that and be able to edit that list, thus forming a 'weak spot in the documentation' list, which currently is there, on the main documentation page.
-- 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
_______________________________________________ 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
________________________________
Be a better Globetrotter. Get better travel answers from someone who knows. Yahoo! Answers - Check it out. _______________________________________________ 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
anyone wanting to do docs please visit http://www.chipin.com/ and start a wiki page and put your buttons on that page so people can donate to you for writing documentation. ./b On Sep 21, 2007, at 2:29 PM, Jason Garland wrote:
How about documentation bounties? Something like $5 - $10 each. ;)
I'll pay a $5 bounty if someone will write up a wiki page on documentation bounties. ;) On 9/21/07, Brian West <brian.west@mac.com> wrote:
anyone wanting to do docs please visit http://www.chipin.com/ and start a wiki page and put your buttons on that page so people can donate to you for writing documentation.
./b
On Sep 21, 2007, at 2:29 PM, Jason Garland wrote:
How about documentation bounties? Something like $5 - $10 each. ;)
_______________________________________________ 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
Actually I'm happy to contribute with documentation (for free ;-) as long as someone tells me what they need. As i'm learning FS more and more, its harder and harder to guess what users with less experience need. On 9/21/07, Jason Garland <jgarland@gmail.com> wrote:
I'll pay a $5 bounty if someone will write up a wiki page on documentation bounties. ;)
On 9/21/07, Brian West <brian.west@mac.com> wrote:
anyone wanting to do docs please visit http://www.chipin.com/ and start a wiki page and put your buttons on that page so people can donate to you for writing documentation.
./b
On Sep 21, 2007, at 2:29 PM, Jason Garland wrote:
How about documentation bounties? Something like $5 - $10 each. ;)
_______________________________________________ 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
_______________________________________________ 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
Actually I'm happy to contribute with documentation (for free ;-) as long as someone tells me what they need. As i'm learning FS more and more, its harder and harder to guess what users with less experience need.
How a Rosetta Stone document? Specifically, people who are familiar with Asterisk could look up how you do something with Asterisk and then the document would translate that into how you do it with FS. I know it's an ambitious project but I thought I'd throw it out there for grins. -MC
ah... that's why Apple called that thing Rosetta... On 9/21/07, Michael Collins <mcollins@fcnetwork.com> wrote:
Actually I'm happy to contribute with documentation (for free ;-) as long as someone tells me what they need. As i'm learning FS more and more, its harder and harder to guess what users with less experience need.
How a Rosetta Stone document? Specifically, people who are familiar with Asterisk could look up how you do something with Asterisk and then the document would translate that into how you do it with FS. I know it's an ambitious project but I thought I'd throw it out there for grins.
-MC
_______________________________________________ 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
Thanks to Raymond Chandler (a.k.a.[intra]lanman) for taking on some of this documentation task. I am going to consider this thread closed. I will open up a new mailing list thread for those intersted to say what kind of docs they would want to see that is not there today, and hopefully some people will also chime in and offer to create these docs. Mike On 9/21/07, Jason Garland <jgarland@gmail.com> wrote:
ah... that's why Apple called that thing Rosetta...
On 9/21/07, Michael Collins <mcollins@fcnetwork.com> wrote:
Actually I'm happy to contribute with documentation (for free ;-) as long as someone tells me what they need. As i'm learning FS more and more, its harder and harder to guess what users with less experience need.
How a Rosetta Stone document? Specifically, people who are familiar with Asterisk could look up how you do something with Asterisk and then the document would translate that into how you do it with FS. I know it's an ambitious project but I thought I'd throw it out there for grins.
-MC
_______________________________________________ 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
_______________________________________________ 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
How about documentation bounties? Something like $5 - $10 each. ;)
Sounds good to me. Does anyone out there have any experience with documentation bounties for any kind of FOSS project? It would be nice to draw upon the experiences of others. -MC
participants (6)
-
Anthony Minessale
-
Brian West
-
Jason Garland
-
Jonas Gauffin
-
Michael Collins
-
Michael Jerris