[osg-users] ANN: Reference Manual for v2.2 now available

Tue Dec 18 16:09:57 PST 2007

Warning... I'm in rare form tonight ;-)

I "sort of" agree with both views on this.

OSG is a great API regardless of whether anyone can use it? That's a  
bit like saying medicine that will save your life is wonderful,  
however it is in a locked box that you cannot open... It's still great  
medicine though right?  Sounds like something from Hitchhikers guide  
to the Galaxy! There is nothing that has intrinsic value (except  
perhaps human beings, but I dare not tread on the philosophical here)  
outside of the value placed on it by those who need or desire it. This  
is basic economics. Just because you value something does not mean it  
"IS" valuable, to the universe or anyone else, but it IS valuable to  
you. The previous assertion that an API is only as good to this one  
gentleman as it's documentation is perfectly valid. He should  
certainly be qualified to determine what is of value to him.

Studying source code and pouring over example programs is simply the  
most inefficient means possible of learning a large and complex API. I  
really don't see how anyone can mount a reasonable defense against  
that fact, and a good many people find this frustrating to the point  
of abandoning or ignoring the technology.

However... Initial efficiency is not the only criteria, both from a  
business point of view and a pedagogical (learning) point of view.

A somewhat weak but still valid argument could be made that learning  
the API this way lends to a deeper and more powerful understanding of  
it. Sometimes people will skim good documentation, find only what they  
need to know and move on without ever appreciating the elegance of  
design, or the depth of power that an API provides. Many open source  
advocates and technologist are very deeply offended by this... my  
opinion is that those sorts of people aren't really bad, they just  
need a good beer and to get laid once and a while. (By-the-way, if  
anyone on this list who has ever helped me is in the Orlando area, I  
would gladly buy you a beer... but your own your own for the latter.)

The fact that the documentation is poor or non-existent is the nature  
of open source. These technologies are built by volunteers, with no  
overbearing boss. Only the most uptight when given a deadline or time  
constraint will voluntarily write good documentation first. Good  
documentation and tutorials take significantly more time to create  
than source code. Simple economics and entropy usually intervene to  
circumvent the best of intentions.

I used to say OpenSource is only free to those who's time is  
worthless. Mr. Hilburn would probably agree, but I have come to  
realize that this was rather ignorant on my own part as well. Nothing  
in life is ever free, especially in the fields most on this list  
practice in. You will always pay either with time, or money; and  
typically you will choose to pay with whichever you have the most of.  
If you don't have either, your just broke... and in good company, so  
there is no point in complaining about it. Although I am currently  
learning OSG in the worst possible manner (as concerning time), it is  
still vastly faster than if I had to build my own scene graph  
technology from scratch. It's rather like being stuck in traffic... "I  
could walk faster"... yes it seems that way for the moment, but you  
will certainly not actually get home faster by leaving your car  
behind. I've built quite enough custom OpenGL engines over the last  
ten years, and looking at OSG I realize there is a lot to be gained by  
a couple months sacrifice on my part. This makes good business sense  
when you look at the larger picture instead of just focusing on a  
single project that is in emergency mode because no time was alloted  
for R&D before coding was to begin... or someone quit and left you  
holding the bag. (I am not making veiled speculation about Mr.  
Hilburn's possible situation... but rather my own!).

It is my observation (let me remind detractors that you cannot  
disagree with my observations... they are mine not yours, although  
admittedly they may not reflect the true nature of the universe ;-)  
that most developers try to master technologies far too fast. Usually  
with a deadline looming. There is a reason we send engineers to school  
before giving them jobs, they need a head start. In industry as well,  
it is best to allocate enough time to get familiar with a new  
technology before trying to build something with it. Alas, again  
economics and entropy often intervene, as I myself have experienced on  
may occasions as well.

I have money (well, "some" money). I have not found a better  
technology than OSG that I can pay money instead of time for (although  
I am still keeping my eye's open ;-). In the mean-time I will spend  
some of that money on some OSG training as soon as it comes to town...

Perhaps one day I'll provide a tutorial or two with the time I'll save  
on future projects <VBG>.

Richard

On Dec 18, 2007, at 3:40 PM, Zachary Hilbun wrote:

> ----- Original Message ----
>> From: Robert Osfield <robert.osfield at gmail.com>
>> To: OpenSceneGraph Users <osg-users at lists.openscenegraph.org>
>> Sent: Friday, December 14, 2007 3:05:38 PM
>> Subject: Re: [osg-users] ANN: Reference Manual for v2.2 now available
>>
>> On Dec 14, 2007 7:59 PM, Zachary Hilbun wrote:
>>> To me an API is only as good as it's documentation.
>>
>> I'd suggest that the OSG is proof that point of view is a perhaps  
>> just
>> a little flawed.
>>
>> Good documentation but a poor API and implementation don't make for
>> successful end user applications.
>>
>> However, with a good API and implementation you do have a least have
>> chance of making something useful.
>
>
> When I say an API is only as good as it's documentation what I mean  
> is that if I don't know how to use something it has no value to me.   
> I've bought/obtained/read the documentation/examples on OSG but  
> found it to be rather incomplete.  Because of the lack of  
> documentation I could wind up blowing a few hundred to a few  
> thousand dollars extra of my time trying to use OSG.  I could  
> instead spend that money buying a package that was already  
> documented.  If a person is a student or hobbiest then they might  
> not value their time that highly.  For me it's a big issue.
>
>
>>
>> I'm not suggesting not having good documentation is not a great thing
>> to have, obviously great documentation and great API and
>> implementation is all what a perfect project would be composed of.
>>
>>> From my experience with the OSG project, its the software that  
>>> solves
>> the problems at the end of the day, and the majority of contributors
>> to the OSG and clients who pay for parts of the OSG to be developed
>> have a problem to solve so they write the code or fund the work to do
>> it. One can say write the documentation first then the software, it
>> might work for you, but so far for the hundreds of contributors to  
>> the
>> OSG this hasn't been the case, the gifts that are given tend to be
>> source code.
>>
>> Thoughts?
>> Robert.
>
> If it were me paying for parts of the OSG to be developed I would  
> want to pay extra to have it documented properly.  My opinion would  
> be that it is cheaper to pay the writer to document it properly than  
> to pay my employes to try to learn it without that documentation.  I  
> would try to impress upon the people doing the funding that their  
> overall costs might be lower if they paid for documentation.
>
> ===============================
> Zachary Hilbun
> Software Contractor
> Dallas, Tx
> 214-350-4207
>
>
> ____________________________________________________________________________________
> Never miss a thing.  Make Yahoo your home page.
> http://www.yahoo.com/r/hs
> _______________________________________________
> osg-users mailing list
> osg-users at lists.openscenegraph.org
> http://lists.openscenegraph.org/listinfo.cgi/osg-users-openscenegraph.org