To me an API is only as good as it's documentation. An API may have wonderful features but if you don't know how to use them it can be useless. I'd rather pay for software that is fully documented than get free software that is not documented. Rather that adding new features to OSG I'd rather see you document fully what you already have. In the future you should not consider a new feature or API as releasable until it is fully documented. I myself like to write the document first and then write the code that implements it. In the case of OSG you could publish the documentation first and have people make comments about whether they like what was being proposed. You are right about the Doxygen output from the source code as being limited. Many people try to use this method as their solution to documentation. It only works as long as they have put the effort into fully commenting each class, function, parameter, and variable. Just having the function and parameter names and possibly a one line comment doesn't help that much. =============================== Zachary Hilbun Software Contractor Dallas, Tx 214-350-4207
----- Original Message ---- From: Paul Martz <[EMAIL PROTECTED]> To: OpenSceneGraph Users <[email protected]> Sent: Friday, December 14, 2007 11:16:11 AM Subject: Re: [osg-users] ANN: Reference Manual for v2.2 now available Let me throw out some ideas, which Bob and I have discussed in the past and also mentioned here on osg-users... * The reference manual, as it stands today, contains some nice supplementary material, but in essence it's Doxygen output from the source code. We could beef up the source code comments for classes and functions, and contribute this back to osg-submissions. This would improve future versions of the ref man. This is a big job and seems worthwhile only if we focus our efforts on stable functionality. * The existing ref man documents osg, osgDB, and osgUtil. We could expand this series to include similar reference material for things like the NodeKits (osgText, osgSim, osgParticle), using OSG in windowing systems (osgViewer, osgManipulator, osgGA), etc. * We could embark on the much-promised and long-awaited "Programming Guide". Again, this is a big job and only seems worthwhile if we focus our efforts on stable features. * We could spend time writing short whitepapers on various OSG topics, similar to Don's useful document on reference-counted memory. We could sell these as PDFs for a couple dollars a pop or something, depending on scope. Possible topics would include rendering order with RenderBins, deriving your own Nodes, Drawables, or StateAttributes, platform-specific topics, resolving build and installation issues, using the Geometry class, performance issues, etc etc, the list is essentially endless. * Any other suggestions for documentation? Paul Martz Skew Matrix Software LLC http://www.skew-matrix.com 303 859 9466 > let me pile on and say i'm thrilled we're done with this too. :) > > i'd also ask of all those users out there who are interested > in better documentation to send us an email: > [EMAIL PROTECTED] - tell us what would is most important to > you in our next book. what you'd like to see, what you think > needs more elaboration, etc. > > we're very interested in ensuring that these books are > relevant, focused, and good, and that we increase overall > goodness of the documentation and tools available to osg users. > > thanks! > bob > > _______________________________________________ > osg-users mailing list > [email protected] > http://lists.openscenegraph.org/listinfo.cgi/osg-users-opensce negraph.org _______________________________________________ osg-users mailing list [email protected] http://lists.openscenegraph.org/listinfo.cgi/osg-users-openscenegraph.org ____________________________________________________________________________________ Be a better friend, newshound, and know-it-all with Yahoo! Mobile. Try it now. http://mobile.yahoo.com/;_ylt=Ahu06i62sR8HDtDypao8Wcj9tAcJ _______________________________________________ osg-users mailing list [email protected] http://lists.openscenegraph.org/listinfo.cgi/osg-users-openscenegraph.org
