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
