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 it’s 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 isn’t 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 don’t
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. 
It’s 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.  I’m 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 don’t 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

Reply via email to