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