Let me say upfront that I realize the people writing OSG are getting nothing out of it for themselves. Also, there is always going to some investment in learning a new package. I think what needs to be addressed is the large amount of time people spend to learn a small amount of OSG.
To me it makes sense to have better documentation, because would you rather have one guy spend an extra hour writing documentation or have 100 guys spend and extra hour each trying to figure out how something works? When I write code I generally write the documentation for each class, function and parameter first. That way its clear in my mind how everything is supposed to work and I can avoid making the mistakes in the code. I think the writing and debugging of the code goes quicker this way than not doing the documentation, and in the end I have a nice document I can give to users. To my way of thinking the documentation should be such that a programmer can look at it and ask me few if any questions. Without that level of documentation the users are going to nickel-and-dime you with questions that should have been addressed by the documentation. You ultimately have the choice of answering the question one-by-one or putting out a document and being done with it. A function or class isnt really ready for release until you have documentation that says what it does and how to use it. You could have the best new feature in the world, but if people dont know what it does or how to use it what have you accomplished? I personally would never ask someone to look through my code to figure out how to call it. Its asking them to do a tremendous amount of work in order to gather a small amount of information. The examples are important because it clears up exactly how things should be done. Comments in the examples would make them much easier to use. Im not really sure what some of the examples do because there is no comment header explaining what is being demonstrated. Comments within the code would make it much easier understand what is going on. I dont think a tutorial is needed for concepts that are common to scene graphs in general. However, some of the OSG concepts are unique to OSG and need to be better explained. --- Gordon Tomlinson <[EMAIL PROTECTED]> wrote: > 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 > =============================== Zachary Hilbun Software Contractor Dallas, Tx ____________________________________________________________________________________ Moody friends. Drama queens. Your life? Nope! - their life, your story. Play Sims Stories at Yahoo! Games. http://sims.yahoo.com/ _______________________________________________ osg-users mailing list osg-users@lists.openscenegraph.org http://lists.openscenegraph.org/listinfo.cgi/osg-users-openscenegraph.org
