[asterisk-users] Manager Interface API's

[Michael Collins]

Douglas has a point, and a legitimate one at that.  Setting aside your
personal feelings about Doug and his style of commenting, please
consider that 'lack of documentation' is either the first- or
second-most-often cited criticism leveled against open-source software
and the OSS community.  Lack of documentation *IS* a serious challenge
with OSS.  That is why it is considered poor style to upload some code
to SourceForge.net and document it by saying, "Look at the source code
and figure it out your self."  Even a modicum of documentation, be it a
brief listing of available methods or a few sample scripts with one or
two sentences explaining what they do is quantum leaps above "source
code only" documentation.

Am I trying to criticize someone who gifts to the world the fruits of
his/her labor?  No.  I'm simply saying that a little documentation makes
such a gift infinitely more useful to the recipients.  One person
spending a few hours documenting his code will save hundreds, perhaps
even thousands, of man-hours of end users "figuring it out."  That is a
serious return on investment if ever there was one.

-MC

> 
> In my opinion, and it seems perfectly logical to me, if someone writes
> some code, but provides no documentation, such that no one can use it,
> then what is the point? They have not provided a solution to anyones
> problem except their own, and have no added value to the open source
> community in any way, except to create 'vapourware' whereby software
> appears to be available, but is unusable, because no one can work out
how
> to make it work.
>