Re: [osg-users] ANN: Reference Manual for v2.2 now available
given the enthusiasm for this from a number of fronts, expect more formal thoughts from the two of us in the next few weeks. and while you're dreaming of sugarplums, dream of your own chapter in the osg gems book. :) happy holidays! bob On Dec 19, 2007, at 3:34 PM, sherman wilcox wrote: However, I like the idea of a community-written OSG Gems book, and I don't want to underestimate the community's willingness to contribute. So, I'll give this some thought, look into other Gems-style books' business models, and see if I can find a way to make this work (time-wise, as an editor). Initial thought: rather than here's how to use some feature in OSG type of articles, it might be better to have here's how I did this really cool thing using OSG or here's how my company is using OSG, if you know what I mean. I think this is more in line with other Gems books I've read. A gems book is a great idea. I second the here's how I did this really cool thing using OSG route. ___ osg-users mailing list osg-users@lists.openscenegraph.org http://lists.openscenegraph.org/listinfo.cgi/osg-users-openscenegraph.org ___ osg-users mailing list osg-users@lists.openscenegraph.org http://lists.openscenegraph.org/listinfo.cgi/osg-users-openscenegraph.org
Re: [osg-users] ANN: Reference Manual for v2.2 now available
Reading this thread, and the threads just like this which pop every six months or so, What is clear is that : 1) When new documentation is announced it is appreciated, but... 2) Very shortly after users come forward and decry how unsufficient the documentation we have... this takes typically two or three post... Its seems that actually announcing documentation seems to provide an excuse to vent ones frustration. 3) Software engineering and frustration often go hand in hand, its part of the life, software engineering is hard and how hard is often mis-understood by those setting deadlines, all too often engineers end up with too little time and too much to do. Over the years this really hasn't changed much, we as software engineers can achieve more with less time thanks to all this lovely technology, much of it open source, or much lower cost and faster hardware, but expectations have moved with this increased capabilities. 4) When people are frustrated and overworked they tend to bark louder, they might have a just cause, but perhaps write in ways that are less congenial than they would when less stressed. They can also be a bit less understanding of others and appreciative of the effort of others. I know this to be the because this happens to me, I can be one of the bears in the picnic garden. To this I'd like to turn around of reflect on items 1 followed shortly after item 2. What this conduct is effectively: Person A gives a gift to everyone, giving the time and expertise. Person B says thanks, but frankly it's not good enough, what you've done is next to useless to me. Now to me... Person B is not being too polite, and certainly not encouraging in any positive way. 5) Venting of frustrations can be contagious, if one person starts being dispropritionatly demanding, then others often get carried into, it would seem to become fair game - sometimes a game of manipulation can arise, not in this thread, but it has happened very occasionally in the past, but these types of threads are the type of ones that can lead in this direction. I think this type of conduct is in part motivated by frustration at not being able to dictate the priorities and work of others. 6) In an open source world the health of a community and it's ecosystem is one that grows strong from shared needs, sharing of expertise, and giving of time and goodwill. The ecosystem is very fluid, in some ways fragile, but in others ways surprisingly robust. What I have learnt that is little one can do to dictate to others, not even as project lead do I have this power, I only have real control over my own priorities and work schedules, and that what gets checked into the official SVN trunk and releases. One can request for assistance on different tasks, and if someone steps up this is awesome and something really appreciated and cherished, but you have to accept what help comes from goodwill, or shared need. Its important to realise that one can't demand things, it simply doesn't work, even for the one who is supposed to be project lead... to have a successful open source ecosystem one has to roll with fluid nature of the community, try to make best of opportunities that arise. 7) Given the context of 6, one simply can't go click ones fingers and expect to things to happen, in fact its counter productive - its harms the community and undermines your ability to achieve your own goals. It might feel good initially to vent your frustration, but isn't healthy or productive. 8) Now maintaining a healthy ecosystem requires one to recognize weaknesses and failures and then fixing them, in the case of bugs its might be hard technically to hunt down and fix a bug but overall is actually something that such a community is relatively well geared up for. There are other things like documentation that might be less technically challenging, but logistically are much harder to create the right conditions that things can happen spontaneously. Curiously the easy things that this community does well is things down out of things one can justify out of self centered motivations i.e. I have a bug, I need it fixed, I've found a fix, its much easier for me if I get this fix in SVN and the next version of the OSG so here it is, please integrate it. The same applies to much of the feature development that goes into the OSG, the motivation of the feature development is to help ones own project, and it just so happens that giving this work away is pretty inexpensive time wise for you, and you get back benefits from other adding to it/fixing it/maintaining. All things that are justifiable from a selfish point of view. Things like documentation and osg-users support are different, its much more out of kindness and
Re: [osg-users] ANN: Reference Manual for v2.2 now available
Thanks for the enjoyable discussion. Bob and I will meet in about 2 weeks and future documentation plans will be a topic of discussion. Some random thoughts follow. Free documentation... I charge for documentation I develop, just like I charge for software I develop. I don't think this is unreasonable. If you sincerely believe that OSG documentation should be free, contract with Bob and I and pay us to write it. Then it's yours, and you can give it away free, just like CGSD/Andes did with the Quick Start Guide. For those of you wishing there was more documentation available, rest assured Bob and I do not intend to stop where we are. However, know that OSG is large, and documenting all of it will take time. I think we've made good progress so far. Without contracts to develop documentation, Bob and I squeeze in documentation development around our (better paying) contractual software development obligations. This environment prohibits any large-scale dedicated documentation projects, and means that documentation will have to come out in small bits and pieces. The idea of writing separate whitepapers on various topics is quite appealing. I see two different approaches here: 1) Bob and I write them all, release them as they are completed, and after we reach some critical mass, we assemble them into the OSG Programming Guide and release that as a book. 2) Members of the OSG community all write articles on various aspects of OSG and submit them to Bob and I. We edit and assemble them and release the OSG Gems book. So I really see those as two different projects. Both seem doable, but the Gems book implicitly assumes community contribution, and past experience indicates the odds for this happening are quite small. (To be fair, having Bob and I write whitepapers implicitly assumes we'll have time to do it -- I think we will, but the papers might not appear as fast as we'd all like.) However, I like the idea of a community-written OSG Gems book, and I don't want to underestimate the community's willingness to contribute. So, I'll give this some thought, look into other Gems-style books' business models, and see if I can find a way to make this work (time-wise, as an editor). Initial thought: rather than here's how to use some feature in OSG type of articles, it might be better to have here's how I did this really cool thing using OSG or here's how my company is using OSG, if you know what I mean. I think this is more in line with other Gems books I've read. Paul Martz Skew Matrix Software LLC http://www.skew-matrix.com 303 859 9466 ___ osg-users mailing list osg-users@lists.openscenegraph.org http://lists.openscenegraph.org/listinfo.cgi/osg-users-openscenegraph.org
Re: [osg-users] ANN: Reference Manual for v2.2 now available
I rather like the idea of community donated white papers, with two pro's editing and compiling them. It seems this would be quick, and bring together a wide range of experiences. I'd be happy to do the chapter OSG for Dummies... I'll throw in a bonus section on mailing list etiquette ;-) Richard A man who is silent appears wise... The fool who speaks removes all doubt. On Dec 19, 2007, at 10:46 AM, Paul Martz wrote: Thanks for the enjoyable discussion. Bob and I will meet in about 2 weeks and future documentation plans will be a topic of discussion. Some random thoughts follow. Free documentation... I charge for documentation I develop, just like I charge for software I develop. I don't think this is unreasonable. If you sincerely believe that OSG documentation should be free, contract with Bob and I and pay us to write it. Then it's yours, and you can give it away free, just like CGSD/Andes did with the Quick Start Guide. For those of you wishing there was more documentation available, rest assured Bob and I do not intend to stop where we are. However, know that OSG is large, and documenting all of it will take time. I think we've made good progress so far. Without contracts to develop documentation, Bob and I squeeze in documentation development around our (better paying) contractual software development obligations. This environment prohibits any large-scale dedicated documentation projects, and means that documentation will have to come out in small bits and pieces. The idea of writing separate whitepapers on various topics is quite appealing. I see two different approaches here: 1) Bob and I write them all, release them as they are completed, and after we reach some critical mass, we assemble them into the OSG Programming Guide and release that as a book. 2) Members of the OSG community all write articles on various aspects of OSG and submit them to Bob and I. We edit and assemble them and release the OSG Gems book. So I really see those as two different projects. Both seem doable, but the Gems book implicitly assumes community contribution, and past experience indicates the odds for this happening are quite small. (To be fair, having Bob and I write whitepapers implicitly assumes we'll have time to do it -- I think we will, but the papers might not appear as fast as we'd all like.) However, I like the idea of a community-written OSG Gems book, and I don't want to underestimate the community's willingness to contribute. So, I'll give this some thought, look into other Gems-style books' business models, and see if I can find a way to make this work (time-wise, as an editor). Initial thought: rather than here's how to use some feature in OSG type of articles, it might be better to have here's how I did this really cool thing using OSG or here's how my company is using OSG, if you know what I mean. I think this is more in line with other Gems books I've read. Paul Martz Skew Matrix Software LLC http://www.skew-matrix.com 303 859 9466 ___ osg-users mailing list osg-users@lists.openscenegraph.org http://lists.openscenegraph.org/listinfo.cgi/osg-users-openscenegraph.org ___ osg-users mailing list osg-users@lists.openscenegraph.org http://lists.openscenegraph.org/listinfo.cgi/osg-users-openscenegraph.org
Re: [osg-users] ANN: Reference Manual for v2.2 now available
I'd be happy to do the chapter OSG for Dummies... We were counting on you for OSG SuperBible! :-) -Paul ___ osg-users mailing list osg-users@lists.openscenegraph.org http://lists.openscenegraph.org/listinfo.cgi/osg-users-openscenegraph.org
Re: [osg-users] ANN: Reference Manual for v2.2 now available
Yikes... I'm already loosing sleep about all the work I have ahead because of OpenGL 3.0 ;-) Richard On Dec 19, 2007, at 2:39 PM, Paul Martz wrote: I'd be happy to do the chapter OSG for Dummies... We were counting on you for OSG SuperBible! :-) -Paul ___ osg-users mailing list osg-users@lists.openscenegraph.org http://lists.openscenegraph.org/listinfo.cgi/osg-users-openscenegraph.org ___ osg-users mailing list osg-users@lists.openscenegraph.org http://lists.openscenegraph.org/listinfo.cgi/osg-users-openscenegraph.org
Re: [osg-users] ANN: Reference Manual for v2.2 now available
However, I like the idea of a community-written OSG Gems book, and I don't want to underestimate the community's willingness to contribute. So, I'll give this some thought, look into other Gems-style books' business models, and see if I can find a way to make this work (time-wise, as an editor). Initial thought: rather than here's how to use some feature in OSG type of articles, it might be better to have here's how I did this really cool thing using OSG or here's how my company is using OSG, if you know what I mean. I think this is more in line with other Gems books I've read. A gems book is a great idea. I second the here's how I did this really cool thing using OSG route. ___ osg-users mailing list osg-users@lists.openscenegraph.org http://lists.openscenegraph.org/listinfo.cgi/osg-users-openscenegraph.org
Re: [osg-users] ANN: Reference Manual for v2.2 now available
- 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
Re: [osg-users] ANN: Reference Manual for v2.2 now available
Hi, I believe Paul @ Skew Matrix and Bob @ Blue Newt would be delighted to be of service! Cheers -- mew -Original Message- From: [EMAIL PROTECTED] [mailto:osg-users- [EMAIL PROTECTED] On Behalf Of Zachary Hilbun Sent: Tuesday, December 18, 2007 2:41 PM To: OpenSceneGraph Users Subject: Re: [osg-users] ANN: Reference Manual for v2.2 now available ... 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 ___ osg-users mailing list osg-users@lists.openscenegraph.org http://lists.openscenegraph.org/listinfo.cgi/osg-users-openscenegraph.org
Re: [osg-users] ANN: Reference Manual for v2.2 now available
On Dec 18, 2007, at 3:40 PM, Zachary Hilbun wrote: - 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 ___ osg-users mailing list osg-users@lists.openscenegraph.org http://lists.openscenegraph.org/listinfo.cgi/osg-users-openscenegraph.org
Re: [osg-users] ANN: Reference Manual for v2.2 now available
Apparently I ran on and on and tried to be too clever and should have just stayed quiet. I did not intend to further the debate, but perhaps capture the nature of open source and community driven projects for those who can't understand why OSG isn't as easy to pick up as say Qt. This nature is not suitable for all developers, but it is still quite useful to many (myself included). Sometimes I enjoy playing devils advocate a little too much ;-) I do not think that OSG is worthless without documentation (to me). I also greatly appreciate the efforts of everyone on this list (including you if I'm not mistaken) to help the newbies, and create the tutorials and sample code for OSG. I do think the level of documentation is sufficient for my needs, but could always be better (I really got quite the head start via Paul's great book). Mailing lists such as these can be more valuable than many books. In fact in a previous posting weeks ago, I stated that I found OSG to be quite refreshing in that it has more tutorials and documentation than most other open source projects I have encountered. I haven't changed my mind. But I am an experienced developer who understands (and was trying to convey in a long winded way) that mastery of a new technology is a significant investment. I was simply (oh, no I suppose there was nothing simple about it) saying, this other gentleman has a valid point... but shouldn't whine about it. I think he probably expected the reference guide to be something like the MSDN reference, or Qt's Assistant. You can't go to Amazon and find several books on OSG, etc. Many people really need this level of support to pick up a new API. no one in the not enough docs camp steps up to change that. I have written one or two sample programs and tutorials in my time... when I graduate from newbie, I promise to contribute something back myself. So can we just agree to disagree? I'm not sure what we disagree on. I see both sides of the argument is all. I haven't been following the thread, and probably should not have just jumped in at the end. I think we can both agree that I haven't gotten enough sleep lately and have probably OD'd on caffeine. I promise to shut up for a while ;-) Richard On Dec 18, 2007, at 8:43 PM, Jean-Sébastien Guay wrote: Hello Richard, Warning... I'm in rare form tonight ;-) Yeah... Well... I don't really see your point in continuing this debate. No one willingly says Hey, you know what? We don't need documentation. You want to pay for it? Why bother!. I think this subject is on the top-5 (maybe even top-2) list of beating a dead horse subjects on this mailing list. On the one hand, you're saying the OSG is worthless without documentation. We all agree with the principle, but the fact of the matter is that a large number of people find what little documentation exists is sufficient to get started, and once you're rolling, everything comes easily. So either your argument is too white or black, or OSG is a counter-example to your argument. I suspect a little of both. See the documentation and tutorials sections on the wiki for great documentation that is not only free, but was also contributed freely by members of the community. See Paul Martz's books for great documentation in the more traditional sense. See the examples in the source code for short, to-the-point code samples. Of course, there can never be enough (and even less too much) documentation. But the debate in itself does not help, since we all have our take on the subject and no one in the not enough docs camp steps up to change that. So can we just agree to disagree? J-S -- __ Jean-Sebastien Guay [EMAIL PROTECTED] http://whitestar02.webhop.org/ This message was sent using IMP, the Internet Messaging Program. ___ osg-users mailing list osg-users@lists.openscenegraph.org http://lists.openscenegraph.org/listinfo.cgi/osg-users-openscenegraph.org ___ osg-users mailing list osg-users@lists.openscenegraph.org http://lists.openscenegraph.org/listinfo.cgi/osg-users-openscenegraph.org
Re: [osg-users] ANN: Reference Manual for v2.2 now available
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 i thought this would be my experience too, after writing it, but i've been surprised. simply seeing all the methods laid out in a logical fashion (rather than how they might be typed into the header), seeing the documentation for a class side-by-side with it's _full_ inheritance hierarchy, and seeing some context (early chapters for osg overview, env var documentation, etc) have actually been interesting. i've even learned a few things in the process of writing / editing these things. yes, you can teach an old dog new tricks. outside the core OSG classes, so a credible documentation job would mean a lot of work for someone. i'll second that comment. at best, these things pay for beer and aspirin, both necessary after beating one's head against doxygen and latex. :) bob ___ osg-users mailing list osg-users@lists.openscenegraph.org http://lists.openscenegraph.org/listinfo.cgi/osg-users-openscenegraph.org
Re: [osg-users] ANN: Reference Manual for v2.2 now available
HI Bob, On Dec 17, 2007 2:18 PM, Bob Kuehne [EMAIL PROTECTED] wrote: i thought this would be my experience too, after writing it, but i've been surprised. simply seeing all the methods laid out in a logical fashion (rather than how they might be typed into the header), seeing the documentation for a class side-by-side with it's _full_ inheritance hierarchy, and seeing some context (early chapters for osg overview, env var documentation, etc) have actually been interesting. I'm longed pondered on the possibility of a documentation process informing design itself, as its once you see high level constructions which are put together into a coherent form that you really see they beauty and the ugly parts of a design. As project lead/developer I'm not interested in the ugly bits, as these are the bits that need some TLC to put right. From a general user/developer point of the view the beauty is probably more important - it gives you a bit of encouragement and inspiration for your own code, and... allows you to forgive the ugly bits when you come across them :-) This type of perspective its hard to get when stuck in the trenches fixing bugs, tweaking bits of API or adding another feature. I do miss the early days of OSG development when I spent a lot of time pondering the high level structure, and doing major refactoring to meet widening goals or taking advantage of new insights - the alchemy period of the OSG. Alas the OSG got too popular and used by people that my time ended being swamped by low level day to day, its gotta work duties. i've even learned a few things in the process of writing / editing these things. yes, you can teach an old dog new tricks. Kinda nice thing about computing, fifteen-twenty years into your career and you are still learning stuff. I have learnt a huge amount about software over the years, but still feel a bit like the % of things to know that I already know about software is actually diminishing over time... Perhaps one day I learn how to write english in a way that is human readable too... ;-) Robert. ___ osg-users mailing list osg-users@lists.openscenegraph.org http://lists.openscenegraph.org/listinfo.cgi/osg-users-openscenegraph.org
Re: [osg-users] ANN: Reference Manual for v2.2 now available
-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
Re: [osg-users] ANN: Reference Manual for v2.2 now available
Hi Tim, On Dec 15, 2007 9:20 AM, Tim Moore [EMAIL PROTECTED] wrote: * 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. In the past we've tried to encourage community documentation, the original pmwiki and then the move to Tracs were both motivated by the hope that they would help such a community effort. Community documentation efforts have so far tended to be small little pockets of activity that soon die down as developers move on to go there day job done - basically everybody is really busy almost all the time. So far real documentation like the Ref Guides, the Quick Start Guide and the Tutorials has happened when you we've had a small set of developers that have a primary goal of doing tutorials/documentation. It takes a lot of time and focus to be able to do it, general community support can help, but I doubt will be a primary resource of manpower. I think we need to get past the thought that if we just create the right conditions for the community to contribute documentation then it'll just happen for anything beyond small stints of couple hours here and there. If we want good documentation then we need to focus on how to create the right conditions to enable individuals to commit the majority of their time for substantive blocks of time. * 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. Um... you want great documentation for free on the promise that you'll buy other great documentation... Experience form the QSG is that if there is free and the is paid for in a hard copy form, free wins almost all the time. Even the paid documentation is unlikely to pay for itself in terms of time put in, so the idea that one can afford the time to write free documentation as well and still have a viable hourly pay rate is simply not realistic. Book sales on niche technical books very rarely exceed the costs of production, we'd need to sell ten's of thousands of books to start seeing any reasonable return. So please guys, can be get a dose of realism here. Good documentation is hard and costly. The community haven't be able to magically write lots of great documentation, free books won't ever pay there way and just eat in sales of bought books, and bought books will always be in the minority and don't pay for themselves. This is the reality as it stands right now. The reality is also that the best documentation we have is subsidised, the QSG by the terrain deformation project, the tutorials from NPS and the ref guides personally by Paul Martz and Bob Kuehne. In part the ref guides are loss leaders for Paul's and Bob's OSG Training, by mostly they are benevolent, a gift of their time and effort and as such should be cherished. We can't just live off the good will of others, people have to pay mortgages, put bread on the table. We need to be realistic about how we create and sustain the conditions that members of the OSG community can help write documentation. Members of the community have to help subsidise the effort of writing documentation via funding others time, or by getting their organizations to put aside blocks of their time towards so they can help with the effort. To me funding of documentation needs to come
Re: [osg-users] ANN: Reference Manual for v2.2 now available
-BEGIN PGP SIGNED MESSAGE- Hash: SHA1 Robert Osfield wrote: Hi Tim, On Dec 15, 2007 9:20 AM, Tim Moore [EMAIL PROTECTED] wrote: * 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. In the past we've tried to encourage community documentation, the original pmwiki and then the move to Tracs were both motivated by the hope that they would help such a community effort. Community documentation efforts have so far tended to be small little pockets of activity that soon die down as developers move on to go there day job done - basically everybody is really busy almost all the time. True enough. I think we need to get past the thought that if we just create the right conditions for the community to contribute documentation then it'll just happen for anything beyond small stints of couple hours here and there. If we want good documentation then we need to focus on how to create the right conditions to enable individuals to commit the majority of their time for substantive blocks of time. I agree with this, more or less, but I will say that the conditions don't exist yet because there isn't critical mass yet of up-to-date documentation. Where is the documentation fairy? :) * 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 ... 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. Um... you want great documentation for free on the promise that you'll buy other great documentation... Uh, no. I don't particularly need the documentation on any of those topics. It would be nice if it existed so that others who don't want to read the source can learn those things, they would be great book chapters, it would suck if the only existent documentation on those subjects wasn't freely available. Experience form the QSG is that if there is free and the is paid for in a hard copy form, free wins almost all the time. Even the paid documentation is unlikely to pay for itself in terms of time put in, so the idea that one can afford the time to write free documentation as well and still have a viable hourly pay rate is simply not realistic. Book sales on niche technical books very rarely exceed the costs of production, we'd need to sell ten's of thousands of books to start seeing any reasonable return. Exactly. So please guys, can be get a dose of realism here. Good documentation is hard and costly. The community haven't be able to magically write lots of great documentation, free books won't ever pay there way and just eat in sales of bought books, and bought books will always be in the minority and don't pay for themselves. This is the reality as it stands right now. So why bother with the non-free books? That isn't meant as a leading question. The reality is also that the best documentation we have is subsidised, the QSG by the terrain deformation project, the tutorials from NPS and the ref guides personally by Paul Martz and Bob Kuehne. In part the ref guides are loss leaders for Paul's and Bob's OSG Training, by mostly they are benevolent, a gift of their time and effort and as such should be cherished. Loss leader is not exactly the same as benevolent, but I basically agree. We can't just live off the good will of others, people have to pay mortgages, put bread on the table. We need to be realistic about how we create and sustain the conditions that members of the OSG community can help write documentation. Members of the community have to help subsidise the effort of writing documentation via funding others time, or by getting their organizations to put aside blocks of their time towards so they can help with the effort. To me funding
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 osg-users@lists.openscenegraph.org http://lists.openscenegraph.org/listinfo.cgi/osg-users-opensce negraph.org ___ osg-users mailing list osg-users@lists.openscenegraph.org http://lists.openscenegraph.org/listinfo.cgi/osg-users-openscenegraph.org
Re: [osg-users] ANN: Reference Manual for v2.2 now available
Paul Martz wrote: * We could spend time writing short whitepapers on various OSG topics, I'd be very much in favour of this form of documentation. It allows users to pick and choose which papers to read, without having to buy lots of doxygen output or stuff they already know. Domain experts could write a paper, with maybe a editor-in-chief to ensure consistency. Admittedly I can see most of this work just coming down to two or three people, but the potential is there. Or maybe the domain expert could just write some notes and someone could be employed as a ghost-writer; this might be attractive to foreign users. Once enough have been written, they could be compiled into a paper book as a sort of OSG Gems. This is something of a Utopian vision I admit, my experience tells me it wouldn't work out like this; but it'd be a reasonable idea to aim for. Incidentally, my offer to proof-read still stands. -JD __ This email has been scanned by the MessageLabs Email Security System. For more information please visit http://www.messagelabs.com/email __ ___ osg-users mailing list osg-users@lists.openscenegraph.org http://lists.openscenegraph.org/listinfo.cgi/osg-users-openscenegraph.org
Re: [osg-users] ANN: Reference Manual for v2.2 now available
Hello Bob and Paul, * 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. I'm always in favor of improving the existing online documentation, so this is a good idea. Some classes are particularly stark, and sometimes it's not clear whether there are preconditions or particular formats for variables. You have to kind of try it, and hopefully your intuition will be right... Even for some straight OpenGL things (I was looking at osg::PolygonOffset lately, so that one jumps to mind), the arguments and units could be documented and typical usage could be discussed... Some things are obscure even in OpenGL's documentation. * 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. The latter would be great. I haven't used the former 3 nodekits much (yet - apart from the occasional text) so I couldn't say personally if I'd find them useful or not. * 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. As JD mentioned, I think that's a good idea as well. The time required for each document would be relatively small, but the focused approach means that new users will probably be more inclined to read the ones that interest them rather than pour over a huge programming guide. I'll see if I can think of other things, but this should keep you occupied for the better part of the next century don't you think? :-) Good work, keep it up. J-S -- __ Jean-Sebastien Guay [EMAIL PROTECTED] http://whitestar02.webhop.org/ This message was sent using IMP, the Internet Messaging Program. ___ osg-users mailing list osg-users@lists.openscenegraph.org http://lists.openscenegraph.org/listinfo.cgi/osg-users-openscenegraph.org
Re: [osg-users] ANN: Reference Manual for v2.2 now available
On Dec 14, 2007 7:59 PM, Zachary Hilbun [EMAIL PROTECTED] 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. 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. Thankfully there has been exceptions, the QSG was a funded documentation effort, and there have been efforts like the ref manual by Paul Martz and Bob Kuehne, but alas the revenue from books does match the level of effort put in so it is a case of labour of love. Work on the tutorials, wiki and examples are also gifts to the community. However, this work is still in minority - few people have time to spend on activities that don't directly result in getting their project deadlines met, and alas few companies have tens of thousands of dollars to put towards serious documentation efforts. I do like the idea of small white papers on different topics, small chunks of documentation are much easier to squeeze in a free day here or there, than spending many months on a major book. Coherency with such works is more difficult though, but still wouldn't detract from their usefulness. Personally I'd love to see enough funding to employ a fulltime technical writer, failing this perhaps part time. Would companies be prepared to help fund documentation effort? Such as by sponsoring or just straight donation? The amounts we'd need to find would be ten of thousands of dollars to be able to do do any significant chunks of work. Thoughts? Robert. ___ osg-users mailing list osg-users@lists.openscenegraph.org http://lists.openscenegraph.org/listinfo.cgi/osg-users-openscenegraph.org
[osg-users] ANN: Reference Manual for v2.2 now available
I'm really excited about this, especially the inclusion of the environment variable reference (which you've seen me pouring my sweat in to these past few weeks). Previously undocumented, OSG's environment variables are a powerful debugging and tuning mechanism that all OSG developers should be familiar with. Order now at http://www.osgbooks.com. A full press release follows. -Paul OpenSceneGraph Reference Manual v2.2 Book Now Available Ann Arbor, Michigan, and Louisville, Colorado, December 13, 2007--Blue Newt Software and Skew Matrix Software are pleased to announce the publication and immediate availability of OpenSceneGraph Reference Manual v2.2, documenting the current release of the cross-platform OpenGL-based scene graph API. The 640-page book is available both as a PDF file and softbound. Bob Kuehne (Blue Newt Software) and Paul Martz (Skew Matrix Software) co-edited the book. OpenSceneGraph Reference Manual v2.2 is the fourth book in the OpenSceneGraph Programming Series. OpenSceneGraph Quick Start Guide, OpenSceneGraph Reference Manual v2.0, and OpenSceneGraph Reference Manual v1.2 are also available. The new book includes an overview of OpenSceneGraph (OSG), changes in the new v2.2 release, and a complete reference for all environment variables that OSG uses. It fully documents all public methods and function parameters in the three core OSG libraries, osg, osgDB, and osgUtil. The reference chapters are generated directly from the OSG source code using Doxygen. The Doxygen configuration files were heavily enhanced to produce a high-quality, readable reference and eliminate clutter. You can order both electronic and softbound editions now at http://www.osgbooks.com. About the Editors Bob Kuehne is a graphics consultant, entrepreneur, engineer, and head of the graphics consultancy, Blue Newt Software. He is the author of OpenGL Programming on Mac OS X. For more information, visit http://www.blue-newt.com. Paul Martz is a 3D graphics software engineer, consultant, and president of Skew Matrix Software. He is the author of OpenGL Distilled and OpenSceneGraph Quick Start Guide. For more information, visit http://www.skew-matrix.com. Bob and Paul collaborate on many OSG development, consulting, training, and technical writing projects. Visit their Web pages for additional information. Blue Newt Software, Ann Arbor, Michigan, USA http://www.blue-newt.com Skew Matrix Software, Louisville, Colorado, USA http://www.skew-matrix.com ___ osg-users mailing list osg-users@lists.openscenegraph.org http://lists.openscenegraph.org/listinfo.cgi/osg-users-openscenegraph.org
Re: [osg-users] ANN: Reference Manual for v2.2 now available
Nice work, thanks for the effort I so much like a dog eared book of a man or web page ;) _ From: [EMAIL PROTECTED] [mailto:[EMAIL PROTECTED] On Behalf Of Paul Martz Sent: Thursday, December 13, 2007 9:40 AM To: 'OpenSceneGraph Users' Subject: [osg-users] ANN: Reference Manual for v2.2 now available I'm really excited about this, especially the inclusion of the environment variable reference (which you've seen me pouring my sweat in to these past few weeks). Previously undocumented, OSG's environment variables are a powerful debugging and tuning mechanism that all OSG developers should be familiar with. Order now at http://www.osgbooks.com. A full press release follows. -Paul OpenSceneGraph Reference Manual v2.2 Book Now Available Ann Arbor, Michigan, and Louisville, Colorado, December 13, 2007--Blue Newt Software and Skew Matrix Software are pleased to announce the publication and immediate availability of OpenSceneGraph Reference Manual v2.2, documenting the current release of the cross-platform OpenGL-based scene graph API. The 640-page book is available both as a PDF file and softbound. Bob Kuehne (Blue Newt Software) and Paul Martz (Skew Matrix Software) co-edited the book. OpenSceneGraph Reference Manual v2.2 is the fourth book in the OpenSceneGraph Programming Series. OpenSceneGraph Quick Start Guide, OpenSceneGraph Reference Manual v2.0, and OpenSceneGraph Reference Manual v1.2 are also available. The new book includes an overview of OpenSceneGraph (OSG), changes in the new v2.2 release, and a complete reference for all environment variables that OSG uses. It fully documents all public methods and function parameters in the three core OSG libraries, osg, osgDB, and osgUtil. The reference chapters are generated directly from the OSG source code using Doxygen. The Doxygen configuration files were heavily enhanced to produce a high-quality, readable reference and eliminate clutter. You can order both electronic and softbound editions now at http://www.osgbooks.com. About the Editors Bob Kuehne is a graphics consultant, entrepreneur, engineer, and head of the graphics consultancy, Blue Newt Software. He is the author of OpenGL Programming on Mac OS X. For more information, visit http://www.blue-newt.com. Paul Martz is a 3D graphics software engineer, consultant, and president of Skew Matrix Software. He is the author of OpenGL Distilled and OpenSceneGraph Quick Start Guide. For more information, visit http://www.skew-matrix.com. Bob and Paul collaborate on many OSG development, consulting, training, and technical writing projects. Visit their Web pages for additional information. Blue Newt Software, Ann Arbor, Michigan, USA http://www.blue-newt.com Skew Matrix Software, Louisville, Colorado, USA http://www.skew-matrix.com ___ osg-users mailing list osg-users@lists.openscenegraph.org http://lists.openscenegraph.org/listinfo.cgi/osg-users-openscenegraph.org
Re: [osg-users] ANN: Reference Manual for v2.2 now available
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 osg-users@lists.openscenegraph.org http://lists.openscenegraph.org/listinfo.cgi/osg-users-openscenegraph.org
