[Freeswitch-users] Call For Help: Janitor Projects

Anthony Minessale anthony.minessale at gmail.com
Wed Apr 1 06:19:54 PDT 2009

have a look.
The phrase has already been coined.

If you look closely we have 2 different perspectives in this thread.

mszlazak is seeking more of the higher level user documentation, the holy
grail magic documentation that
is like the hitchhikers guide to the galaxy or harry potter's marauder's map
can tune into what you need to know
or what you don't understand and magically adjusts.  This is normal, we have
a lot of users like that.  The majority of users
will treat us like they are buying the software from us and impose their
expectations on us.  It's helpful to us, it lets us
see things from their perspective.

Seven is looking it at more from a developer's perspective, he's actually
willing to take the time to add things
to the wiki and he wants to understand how the code works.  This is a good
thing too, there are far less people of this type
in our community but they are crucial.

Core developers document by explaining what they are doing to people like
Seven or by putting a reminder in the commit notes which are later
translated into the CHANGELOG for the releases.  Michael, the author of this
thread has added countless pages of documentation to the wiki this way.
It's easy to say the author should document everything.  There is close to
300,000 lines of
code in just the src directory in the FreeSWITCH tree (that is all code we
wrote not counting any of the depends libs or any other form of pre-existing
code).  I personally wrote the majority of that code so, I really appricate
it when the communiuty gives me a few minutes to take a break while they
document it.  The best people to document the high level fuctionality  is
not the author btw.  It's the first few people who use it.  Most likely they
are developing a product from it and they intend to profit from it in one
way or another and its a fair tradeoff to have the section of functionality
explained to them in exchange from wikifying it from their perspective.  The
perspective of the author will be dry and mechinacal where that
first-time-user version of the documentation will make much more sense to
future readers.

When it comes to the low level documentation, the C functions, we also need
someone to help us with that if they feel there is not enough.  We write
code, we know how it works.  If other people cannot figure out how it works,
they will ask us and in the end it will be doucmented.  About 5% or less of
people in the community even have to look in the code for the core.  The
whole point of the FreeSWITCH design is to push everything up to scripts,
remote connections and dialplan logic to let people concentrate on good
ideas instead of the evil logic necessary to properly engineer a telephony
engine.  So I recommend anybody interested starts out making sure there is
ample documentation for the embedded and external API for lua, js, perl,
python, ESL etc.  Then anybody who really likes C code can start with the
module API layer and then dig deeper into the core code and learn how it
works and if the documentation is not enough, add some, we appriciate any
help we can get.

2009/4/1 <mszlazak at aol.com>

>  First off. I would not call it a "janitors project" since that may offend
> some. A second problem is your notion that documentation is
> "not-quite-as-important" a task as writing code. I'm think many would say
> you have that backwards. There is nothing more effective in evolving
> FreeSwitch than good documentation which helps further development and is an
> important part of "customer service." Good customer service is then a part
> of "sales and marketing." Much more often than not, It's sales and marketing
> that is more important to making something a "real product"  than
> engineering. "Build it and they will come" almost never works.
> Anyway, I think you need a new name for this project.
>  -----Original Message-----
> From: Michael Collins <msc at freeswitch.org>
> To: freeswitch-users at lists.freeswitch.org <
> freeswitch-users at lists.freeswitch.org>;
> freeswitch-dev at lists.freeswitch.org
> Sent: Tue, 31 Mar 2009 5:10 pm
> Subject: [Freeswitch-users] Call For Help: Janitor Projects
>  Dear FreeSWITCH Community:
> As you know, FreeSWITCH has been growing leaps and bounds and it's going to
> keep growing as the word spreads. The core development team of Anthony,
> Mike, and Brian are very appreciative of the community's help and
> involvement in the project. Simply put: the community is awesome!
> Some have asked how they can help. Most of us are not software developers,
> but that doesn't mean we can't help to grow the FreeSWITCH ecosystem. To
> this end I've started a "janitor projects" wiki page:
> http://wiki.freeswitch.org/wiki/Janitor_Projects
> We say "janitor" projects because they are things that help keep the
> project clean and organized, just like the janitor cleans an office, takes
> out the trash, replaces the toilet paper, etc. These are valuable services
> that we sometimes take for granted. However, I think we can all appreciate
> that the FreeSWITCH project would be better served if the developers could
> focus on writing code, fixing bugs, etc. and not on the easier,
> not-quite-as-important janitorial tasks. To that end we are inviting all who
> wish to volunteer to please visit the above wiki page and check out some of
> the projects listed so far. Email me off list if you'd like to volunteer to
> help. I'm maintaining a list of "janitors" and what they are helping with.
> If you have ideas for other janitor projects then by all means email them to
> me and we'll discuss them.
> Thanks again for being such a great community!
> -Michael S Collins
> IRC: mercutioviz
> See you at ClueCon 2009!  http://www.cluecon.com
> _______________________________________________
> 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
> ------------------------------
> New Low Prices on Dell Laptops - Starting at $399<http://pr.atwola.com/promoclk/100126575x1220631247x1201390185/aol?redir=http:%2F%2Fad.doubleclick.net%2Fclk%3B213540506%3B35046329%3Bx>
> _______________________________________________
> 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

Anthony Minessale II

FreeSWITCH http://www.freeswitch.org/
ClueCon http://www.cluecon.com/

AIM: anthm
MSN:anthony_minessale at hotmail.com <MSN%3Aanthony_minessale at hotmail.com>
GTALK/JABBER/PAYPAL:anthony.minessale at gmail.com<PAYPAL%3Aanthony.minessale at gmail.com>
IRC: irc.freenode.net #freeswitch

FreeSWITCH Developer Conference
sip:888 at conference.freeswitch.org <sip%3A888 at conference.freeswitch.org>
iax:guest at conference.freeswitch.org/888
googletalk:conf+888 at conference.freeswitch.org<googletalk%3Aconf%2B888 at conference.freeswitch.org>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.freeswitch.org/pipermail/freeswitch-users/attachments/20090401/f8bc7440/attachment-0002.html 

More information about the FreeSWITCH-users mailing list