boils down to an age old saying, you get what you pay for when it comes to documentation with open source projects
SGI produced some excellent Performer manuals that helped some folks they also spent alot of man hours and money producing these ( BTW these are still very use for people new to Scenegraphs and 3d graphics becuase the concepts are the same, the only real new things is programmable GPU's , I still recommend these to newbies) Problem to ay is too many folks expect everthing for free and expect software to write itsself or someone to do it for them, the only way to learn how to do something is to do it, and no book is ever going to give every one all the information they think the should have or what they want to achieve. As has been said if some people feel theres a short coming in th FREE documentation,examples, samples or code etc then please provide better examples, better docs etc... or if you expect someone else to do if for you then exect to pay for it... Best Regards Gordon __________________________________________________________ Gordon Tomlinson Email : gordon.tomlinson @ overwatch.com YIM/AIM: Gordon3dBrit MSN IM : Gordon3dBrit @ 3dSceneGraph.com __________________________________________________________ Telephone (Cell): (+1) 571-265-2612 <-- Note New Number Telephone (Work): (+1) 703-437-7651 "Self defence is not a function of learning tricks but is a function of how quickly and intensely one can arouse one's instinct for survival" - Master Tambo Tetsura -----Original Message----- From: [EMAIL PROTECTED] [mailto:[EMAIL PROTECTED] Behalf Of Robert Penn Taylor Sent: Thursday, August 23, 2007 1:02 PM To: osg-users@lists.openscenegraph.org Subject: Re: [osg-users] Tutorials Robert Osfield wrote: > > In other projects I do occasionally look for documentation, but rarely > does it help me more than a succinct code example. If you are > experienced programmer than its the code that tells you everything. > I'd say the code *can* tell you everything, but there are many cases in which reading "the code" is just about the least time-efficient method of figuring it out. Let's say I want to rotate a matrix. Which method does what I need? It's easy enough to find that osg::Matrix:: rotate, setRotate, and makeRotate exist, but what does each one do? Where do I look? In the MatrixImplementation header? In the associated cpp? How about the doxygen generated comments? Or maybe I hunt through 50 examples, none of which has anything explicitly to do with how to rotate a matrix. Okay, that's four places to look, none of them are terribly enlightening, and I just spent how long -- probably an hour by the time I backtrack all the necessary code to understand what's going on in an example -- trying to figure out which method to use to rotate a matrix. Maybe by this point I have it and maybe I don't. Contrast this with the existence of some sort of documentation that breaks the API down into functional units. I look in doc for the maths unit, then matrix operations, and there it is: matrix rotations. A few short examples and a solid explanation of the three ways in osg to accomplish this. Time spent is maybe five minutes. Or how about clear doxygen comments in the code? Take a look at http://www.wxwidgets.org/manuals/stable/wx_wxstring.html#wxstringremove for an example of clear comments generated from a header. You don't even need a code example when comments are this clear. Notice also how the documentation clearly indicates that the function is deprecated, and even tells you what to replace it with. (Notice also that they maintain backwards compatibility through at least one major release number.) When I'm doing wxWidgets work, the doxygen docs are just about the only reference I need. I rarely need to look at sample code, even though it does exist. OSG is exactly the reverse, and I notice that it often eventually results in a frustrated post to the users list asking how to do something relatively simple. Perhaps the osg community can take a leaf from wxWidgets' notebook? I'm not bashing Robert or anyone else for the fact that such documentation doesn't exist. I understand how much time it takes, especially when the API code changes as frequently as osg's. But an answer of "look at the code" just doesn't cut it in many situations. > I do wonder if too many developers these days are expecting to put in > too little real effort for the amount of results they are wanting. > Programming is hard. Real-time graphics is a BIG topic. To master > them you have lavish lots of time. > One has to lavish a lot of time, yes, but that time should be lavished learning the maths and concepts of RT graphics, along with some amount of time learning an API. That time shouldn't be spent digging through API code trying to understand how to use basic operations that could be easily documented. Again, I'm not bashing anyone. But in my opinion most folks are not being unreasonable in the complaint that the documentation is lacking. And it's mighty hard to generate that documentation when you're still trying to figure it out yourself. Well, that pretty much wraps up my argument for why people complaining about documentation are not automatically lazy, stupid, or bad programmers. -Penn Taylor _______________________________________________ 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
