----- Original Message ----
> From: Robert Osfield <[EMAIL PROTECTED]>
> To: OpenSceneGraph Users <osg-users@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@lists.openscenegraph.org
http://lists.openscenegraph.org/listinfo.cgi/osg-users-openscenegraph.org
