[asterisk-users] Manager Interface API's

[Don]

>> 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.

We were talking about Free open-source code...The end user is saving and 
getting a return on investment...the programmer isn't get anything but a pat 
on the back for making documentation.

I totally agree that if I were making something that was specifically being 
released to the public I would document it.

If I just made something that I needed...and then decided to release it to 
the public incase anyone else needed it...I wouldn't waste my time 
documenting it...because there is no ROI to me for that....

----- Original Message ----- 
From: "Michael Collins" <mcollins at fcnetwork.com>
To: "Asterisk Users Mailing List - Non-Commercial Discussion" 
<asterisk-users at lists.digium.com>
Sent: Wednesday, August 16, 2006 4:49 PM
Subject: RE: [asterisk-users] Manager Interface API's


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.
>
_______________________________________________
--Bandwidth and Colocation provided by Easynews.com --

asterisk-users mailing list
To UNSUBSCRIBE or update options visit:
   http://lists.digium.com/mailman/listinfo/asterisk-users


-- 
No virus found in this incoming message.
Checked by AVG Free Edition.
Version: 7.1.405 / Virus Database: 268.11.1/421 - Release Date: 8/16/2006