[asterisk-users] Manager Interface API's

Mike Weaver mweaver at misteam.net
Wed Aug 16 17:16:50 MST 2006


That's nothing.  As a person with 3 degrees in English, I once spent 
months writing beautiful documentation for a project I was writing, only 
to realize I was such a lousy coder I'd never work.  Count your blessings...

Don wrote:

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




More information about the asterisk-users mailing list