<html xmlns:v="urn:schemas-microsoft-com:vml" xmlns:o="urn:schemas-microsoft-com:office:office" xmlns:w="urn:schemas-microsoft-com:office:word" xmlns:st1="urn:schemas-microsoft-com:office:smarttags" xmlns="http://www.w3.org/TR/REC-html40">
<head>
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=us-ascii">
<meta name=Generator content="Microsoft Word 11 (filtered medium)">
<!--[if !mso]>
<style>
v\:* {behavior:url(#default#VML);}
o\:* {behavior:url(#default#VML);}
w\:* {behavior:url(#default#VML);}
.shape {behavior:url(#default#VML);}
</style>
<![endif]--><o:SmartTagType
namespaceuri="urn:schemas-microsoft-com:office:smarttags" name="country-region"/>
<o:SmartTagType namespaceuri="urn:schemas-microsoft-com:office:smarttags"
name="City"/>
<o:SmartTagType namespaceuri="urn:schemas-microsoft-com:office:smarttags"
name="place"/>
<o:SmartTagType namespaceuri="urn:schemas-microsoft-com:office:smarttags"
name="PersonName"/>
<!--[if !mso]>
<style>
st1\:*{behavior:url(#default#ieooui) }
</style>
<![endif]-->
<style>
<!--
/* Font Definitions */
@font-face
{font-family:Courier;
panose-1:2 7 4 9 2 2 5 2 4 4;}
@font-face
{font-family:Tahoma;
panose-1:2 11 6 4 3 5 4 4 2 4;}
/* Style Definitions */
p.MsoNormal, li.MsoNormal, div.MsoNormal
{margin:0in;
margin-bottom:.0001pt;
font-size:12.0pt;
font-family:"Times New Roman";}
a:link, span.MsoHyperlink
{color:blue;
text-decoration:underline;}
a:visited, span.MsoHyperlinkFollowed
{color:blue;
text-decoration:underline;}
span.EmailStyle17
{mso-style-type:personal-reply;
font-family:Arial;
color:navy;}
@page Section1
{size:8.5in 11.0in;
margin:1.0in 1.25in 1.0in 1.25in;}
div.Section1
{page:Section1;}
-->
</style>
</head>
<body lang=EN-US link=blue vlink=blue>
<div class=Section1>
<p class=MsoNormal><font size=2 color=navy face=Arial><span style='font-size:
10.0pt;font-family:Arial;color:navy'>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.” <o:p></o:p></span></font></p>
<p class=MsoNormal><font size=2 color=navy face=Arial><span style='font-size:
10.0pt;font-family:Arial;color:navy'><o:p> </o:p></span></font></p>
<p class=MsoNormal><font size=2 color=navy face=Arial><span style='font-size:
10.0pt;font-family:Arial;color:navy'>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. <o:p></o:p></span></font></p>
<p class=MsoNormal><font size=2 color=navy face=Arial><span style='font-size:
10.0pt;font-family:Arial;color:navy'><o:p> </o:p></span></font></p>
<p class=MsoNormal><font size=2 color=navy face=Arial><span style='font-size:
10.0pt;font-family:Arial;color:navy'>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.”<o:p></o:p></span></font></p>
<p class=MsoNormal><font size=2 color=navy face=Arial><span style='font-size:
10.0pt;font-family:Arial;color:navy'><o:p> </o:p></span></font></p>
<p class=MsoNormal><font size=2 color=navy face=Arial><span style='font-size:
10.0pt;font-family:Arial;color:navy'>If people <i><span style='font-style:italic'>really</span></i>
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.)<o:p></o:p></span></font></p>
<p class=MsoNormal><font size=2 color=navy face=Arial><span style='font-size:
10.0pt;font-family:Arial;color:navy'><o:p> </o:p></span></font></p>
<p class=MsoNormal><font size=2 color=navy face=Arial><span style='font-size:
10.0pt;font-family:Arial;color:navy'>Just a thought.<o:p></o:p></span></font></p>
<p class=MsoNormal><font size=2 color=navy face=Arial><span style='font-size:
10.0pt;font-family:Arial;color:navy'><o:p> </o:p></span></font></p>
<p class=MsoNormal><font size=2 color=navy face=Arial><span style='font-size:
10.0pt;font-family:Arial;color:navy'>-MC<o:p></o:p></span></font></p>
<p class=MsoNormal><font size=2 color=navy face=Arial><span style='font-size:
10.0pt;font-family:Arial;color:navy'><o:p> </o:p></span></font></p>
<p class=MsoNormal><font size=2 color=navy face=Arial><span style='font-size:
10.0pt;font-family:Arial;color:navy'>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 <i><span style='font-style:italic'>arrived</span></i>.
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!<o:p></o:p></span></font></p>
<p class=MsoNormal><font size=2 color=navy face=Arial><span style='font-size:
10.0pt;font-family:Arial;color:navy'><o:p> </o:p></span></font></p>
<div style='border:none;border-left:solid blue 1.5pt;padding:0in 0in 0in 4.0pt'>
<div>
<div class=MsoNormal align=center style='text-align:center'><font size=3
face="Times New Roman"><span style='font-size:12.0pt'>
<hr size=2 width="100%" align=center tabindex=-1>
</span></font></div>
<p class=MsoNormal><b><font size=2 face=Tahoma><span style='font-size:10.0pt;
font-family:Tahoma;font-weight:bold'>From:</span></font></b><font size=2
face=Tahoma><span style='font-size:10.0pt;font-family:Tahoma'>
freeswitch-users-bounces@lists.freeswitch.org
[mailto:freeswitch-users-bounces@lists.freeswitch.org] <b><span
style='font-weight:bold'>On Behalf Of </span></b>Anthony Minessale<br>
<b><span style='font-weight:bold'>Sent:</span></b> Friday, September 21, 2007
11:24 AM<br>
<b><span style='font-weight:bold'>To:</span></b> <st1:PersonName w:st="on">freeswitch-users@lists.freeswitch.org</st1:PersonName><br>
<b><span style='font-weight:bold'>Subject:</span></b> Re: [Freeswitch-users]
Should I choose FreeSwitch?</span></font><o:p></o:p></p>
</div>
<p class=MsoNormal><font size=3 face="Times New Roman"><span style='font-size:
12.0pt'><o:p> </o:p></span></font></p>
<div>
<p class=MsoNormal style='margin-bottom:12.0pt'><font size=3 face=Courier><span
style='font-size:12.0pt;font-family:Courier'>Ha,<br>
<br>
Too bad all the text going back and forth in this thread<br>
was not actual documentation instead of deliberations about<br>
documentation practices or we'd be done already =D<br>
<br>
Anyone who want's to do anything to help the documentation<br>
effort by my guest to make any wiki page etc you need.<br>
I don't see a mad rush of volunteers so I won't hold my breath<br>
or anything but if I run out of bugs to fix and code to write<br>
I will start working on this myself.....<o:p></o:p></span></font></p>
<div>
<p class=MsoNormal><font size=3 face=Courier><span style='font-size:12.0pt;
font-family:Courier'> <o:p></o:p></span></font></p>
</div>
<div>
<p class=MsoNormal><font size=3 face=Courier><span style='font-size:12.0pt;
font-family:Courier'>Anthony Minessale II<br>
<br>
FreeSWITCH <a href="http://www.freeswitch.org/" target="_blank">http://www.freeswitch.org/</a><br>
ClueCon <a href="http://www.cluecon.com/" target="_blank">http://www.cluecon.com/</a><br>
<br>
AIM: anthm<br>
MSN:anthony_minessale@hotmail.com<br>
GTALK/JABBER/PAYPAL:anthony.minessale@gmail.com<br>
IRC: irc.freenode.net #freeswitch<o:p></o:p></span></font></p>
</div>
<div>
<p class=MsoNormal><font size=3 face=Courier><span style='font-size:12.0pt;
font-family:Courier'><br>
FreeSWITCH Developer Conference<br>
sip:888@conference.freeswitch.org<br>
iax:guest@conference.freeswitch.org/888<br>
googletalk:conf+888@conference.freeswitch.org<br>
pstn:213-799-1400<o:p></o:p></span></font></p>
</div>
<div>
<p class=MsoNormal style='margin-bottom:12.0pt'><font size=3 face=Courier><span
style='font-size:12.0pt;font-family:Courier'><o:p> </o:p></span></font></p>
<div>
<p class=MsoNormal style='margin-bottom:12.0pt'><font size=3
face="Times New Roman"><span style='font-size:12.0pt'>----- Original Message
----<br>
From: Jonas Gauffin <jonas.gauffin@gmail.com><br>
To: <st1:PersonName w:st="on">freeswitch-users@lists.freeswitch.org</st1:PersonName><br>
Sent: Thursday, September 20, 2007 8:47:15 AM<br>
Subject: Re: [Freeswitch-users] Should I choose FreeSwitch?<o:p></o:p></span></font></p>
<div>
<p class=MsoNormal><font size=3 face="Times New Roman"><span style='font-size:
12.0pt'>I'm not talking about if people can or can't edit the pages.<br>
<br>
I'm talking about users that want to find or read documentation (not<br>
contribute). For instance: New users.<br>
<br>
They want to find documentation and read it. Those users can give<br>
valuable feedback to us (so that we can make the documentation better)<br>
if they do not understand it / think that some documentation is<br>
missing.<br>
<br>
What I want is a way for those users to give us that feedback. They<br>
can, as you say, edit the pages and add their questions /
suggestions<br>
directly in the page. But what will a page look like if 20 users have<br>
added questions / suggestions for improvement on it?<br>
<br>
Again: I'm not talking about user who can contribute with information<br>
(having know-how), but about new users who want to use/configure<br>
FreeSwitch (like new users).<br>
<br>
There are a section on the first page called "Community and Support"<br>
on the first page which tells the user how to get help. Maybe there<br>
should also be a section called "How to give feedback" too?<br>
<br>
<br>
On 9/20/07, Trixter aka Bret McDanel <trixter@0xdecafbad.com> wrote:<br>
> On 9/20/07, Jonas Gauffin <jonas.gauffin@gmail.com> wrote:<br>
> > Ahh.. My mistake. I searched for both "FAQ" and
"Frequently asked<br>
> > questions" without getting a hit.<br>
> ><br>
><br>
> The searching on that site is admittedly a bit weak, I do not know<br>
> what to do about that, nor do I have any control over that since its<br>
> the people that have direct control of the site. I will talk to<br>
> someone and see if there is anything they can do in that regard.<br>
><br>
><br>
> > Then I saw this in the documentation guidelines: "Try to avoid
FAQs".<br>
> > My conclusion was therefore that it was removed. But I found it now
=)<br>
> ><br>
><br>
> The 'try to avoid faqs' in the guidelines refers to documenting a<br>
> module or something else. If you were to document mod_something
there<br>
> shouldnt be a need for a FAQ about that module, since the<br>
> documentation should explain what it does and how to use it. If
you<br>
> feel the need for a FAQ on mod_something then perhaps the<br>
> documentation itself should be extended to answer those questions. :)<br>
><br>
><br>
><br>
> > My point was that people who can't contribute with information should<br>
> > be able to REQUEST information. Those requests shouldn't be added in<br>
> > the documentation, but in the Talk pages or special request pages<br>
><br>
> I dont understand, they have to edit a wiki page to request<br>
> information or add to the talk section, but they cant edit a different<br>
> wiki page to actually create documentation? Almost seems like
its an<br>
> extra layer of stuff that people would have to actively seek out to<br>
> read and then update the documentation just to create this process.<br>
><br>
> Why cant people contribute to the documentation effort but could<br>
> contribute to wiki pages on the same system?<br>
><br>
><br>
><br>
> ><br>
> > I created the documentation guidelines page too :) But that's for ppl<br>
> > that can actually contribute in the documentation. Not for ppl that
as<br>
> > missing or not understanding some documentation.<br>
> ><br>
><br>
> everyone can contribute, you make it sound like only some people are<br>
> allowed and others cant. Maybe that is my misunderstanding when
you<br>
> constantly refer to people who cant edit documentation but can edit<br>
> some other page on the wiki.<br>
><br>
> I just dont understand why this extra layer is a good thing, if people<br>
> can add to those pages they can add to the documentation itself.<br>
> There is a list of missing documents, which I periodically update, as<br>
> well as a list of empty pages which I update at the same
time. If<br>
> someone were to link to a page that doesnt exist, during the<br>
> generation of the PDF I would see that and be able to edit that list,<br>
> thus forming a 'weak spot in the documentation' list, which currently<br>
> is there, on the main documentation page.<br>
><br>
><br>
><br>
> --<br>
> Trixter <a href="http://www.0xdecafbad.com" target="_blank">http://www.0xdecafbad.com</a>
Bret McDanel<br>
> <st1:City w:st="on">Belfast</st1:City> +44 28 9099
6461 <st1:country-region w:st="on"><st1:place
w:st="on">US</st1:place></st1:country-region> +1 516 687 5200<br>
> <a href="http://www.trxtel.com" target="_blank">http://www.trxtel.com</a>
the phone company that pays you!<br>
><br>
> _______________________________________________<br>
> Freeswitch-users mailing list<br>
> Freeswitch-users@lists.freeswitch.org<br>
> <a href="http://lists.freeswitch.org/mailman/listinfo/freeswitch-users"
target="_blank">http://lists.freeswitch.org/mailman/listinfo/freeswitch-users</a><br>
> UNSUBSCRIBE:<a
href="http://lists.freeswitch.org/mailman/options/freeswitch-users"
target="_blank">http://lists.freeswitch.org/mailman/options/freeswitch-users</a><br>
> <a href="http://www.freeswitch.org" target="_blank">http://www.freeswitch.org</a><br>
><br>
<br>
_______________________________________________<br>
Freeswitch-users mailing list<br>
Freeswitch-users@lists.freeswitch.org<br>
<a href="http://lists.freeswitch.org/mailman/listinfo/freeswitch-users"
target="_blank">http://lists.freeswitch.org/mailman/listinfo/freeswitch-users</a><br>
UNSUBSCRIBE:<a
href="http://lists.freeswitch.org/mailman/options/freeswitch-users"
target="_blank">http://lists.freeswitch.org/mailman/options/freeswitch-users</a><br>
<a href="http://www.freeswitch.org" target="_blank">http://www.freeswitch.org</a><o:p></o:p></span></font></p>
</div>
</div>
<p class=MsoNormal><font size=3 face=Courier><span style='font-size:12.0pt;
font-family:Courier'><o:p> </o:p></span></font></p>
</div>
</div>
<p class=MsoNormal><font size=3 face="Times New Roman"><span style='font-size:
12.0pt'><o:p> </o:p></span></font></p>
<div class=MsoNormal align=center style='text-align:center'><font size=3
face="Times New Roman"><span style='font-size:12.0pt'>
<hr size=1 width="100%" align=center>
</span></font></div>
<p class=MsoNormal><font size=3 face="Times New Roman"><span style='font-size:
12.0pt'>Be a better Globetrotter. <a
href="http://us.rd.yahoo.com/evt=48254/*http:/answers.yahoo.com/dir/_ylc=X3oDMTI5MGx2aThyBF9TAzIxMTU1MDAzNTIEX3MDMzk2NTQ1MTAzBHNlYwNCQUJwaWxsYXJfTklfMzYwBHNsawNQcm9kdWN0X3F1ZXN0aW9uX3BhZ2U-?link=list&sid=396545469">Get
better travel answers </a>from someone who knows.<br>
Yahoo! Answers - Check it out. <o:p></o:p></span></font></p>
</div>
</div>
</body>
</html>