[Freeswitch-users] Should I choose FreeSwitch?

Fri Sep 21 15:02:35 EDT 2007

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 at lists.freeswitch.org
[mailto:freeswitch-users-bounces at lists.freeswitch.org] On Behalf Of
Anthony Minessale
Sent: Friday, September 21, 2007 11:24 AM
To: freeswitch-users at 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 at hotmail.com
GTALK/JABBER/PAYPAL:anthony.minessale at gmail.com
IRC: irc.freenode.net #freeswitch

FreeSWITCH Developer Conference
sip:888 at conference.freeswitch.org
iax:guest at conference.freeswitch.org/888
googletalk:conf+888 at conference.freeswitch.org
pstn:213-799-1400

----- Original Message ----
From: Jonas Gauffin <jonas.gauffin at gmail.com>
To: freeswitch-users at 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 at 0xdecafbad.com> wrote:
> On 9/20/07, Jonas Gauffin <jonas.gauffin at 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 at 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 at 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. 

-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.freeswitch.org/pipermail/freeswitch-users/attachments/20070921/6399e32a/attachment-0001.html 