-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 Paul Martz wrote: > 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. I haven't been tempted by the reference manual book because I know how to navigate the source code and can't see how the relatively sparse comments therein would be more helpful compiled together. I think the situation is even worse once you get outside the core OSG classes, so a credible documentation job would mean a lot of work for someone. > > * 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. I'd love to see this and I know it would be a big job. I think you could enlist the community's help with this and still make as much money with the book at the end of the day. > > * 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. > This route would be quite unfortunate. Like everyone else on this list I'd love to see documentation on these topics, but as someone who has shared what he has learned the hard way on some of these very topics, I think it would be a shame if the authoritative advanced documentation was in a per-pay product. Having this kind of documentation freely available shows off to the world the advanced uses of OSG, inspires the community, encourages others to give back, etc.
I absolutely respect your need to make a living, and the above subjects should certainly be covered in any book on OSG. I might suggest that you start shells for these subjects on Wiki pages, either the official OSG one or your own where you make it clear that you retain a "compilation" copyright. Add what you know to the pages, then later use them as base material for the book. I don't know the economics of your book sales, but I can only believe that high-quality free documentation won't hurt the sales of a good book on OSG. > * Any other suggestions for documentation? It's interesting to look at the documentation of the ogre3d.org project. Ogre3d is a game rendering engine with many of the same aims as OSG. It's documentation situation is quite different from OSG's: good class documentation, an excellent reference manual for the "scripts" system which creates materials and effects, and copious tutorials on a whole range of production and programming subjects. I know this sort of thing doesn't grow on trees, and some of it must have been funded work, but a lot of it was contributed by their community. It has clearly helped Ogre3d to be popular. Tim -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.7 (GNU/Linux) Comment: Using GnuPG with Fedora - http://enigmail.mozdev.org iD8DBQFHY5xSeDhWHdXrDRURAlIfAJwKXDB4qa18+SlUTKOE5BD2yf04iQCffybP mBfLNNnlU93YOzC5qsxxrJA= =qak4 -----END PGP SIGNATURE----- _______________________________________________ osg-users mailing list osg-users@lists.openscenegraph.org http://lists.openscenegraph.org/listinfo.cgi/osg-users-openscenegraph.org
