[ODE] Updating ODE documentation (was: hello world)

[Shaul Kedem]

Hmm...

 Well, just so people will see the other side of the
coin I must comment on Adam's email.

 First, using formulas or textual representations of
the formulas will get the mathematics - oriented
people to understand what is going on, but what about
the programmers who wants to use ODE as a tool?

 Second, such names as "coefficient of restitution"
and not "bounce" are OK for people with english -
based physics knowledge but who ever learned physics
(in high school) using another language will have to
go and discover that "coefficient of restitution" is
actually "bounce" of some sort.

 So my suggestion is that the documentation will keep
the "simple" terms next to the "more accurate" ones,
keep the current documentation next to the formal
representations and most importantly - include some
example (buggy maybe) code with simple notes on how to
create such a demonstration. I must say I find it very
difficult to cope with all of the rigid dynamics
knowledge in ODE and I feel the more people are
talking about it the more it gets away from my grasp
(I am a professional C programmer for the last 5
years).

 Basic understanding of rigid body dynamics and other
terms is an important step in bringing more people
into the area of physics engines.

shul

--- Adam Moravanszky <amoravanszky at dplanet.ch> wrote:
> A suggestion for doc improvement:
> 
> Methinks the documentation really needs to document
> the meanings of ODE
> parameters better.  For example, there is a contact
> bounce parameter.  The
> docs say that it has to be in [0,1], and describes
> the semantics of the two
> extremes.  But it has nothing more, so Russ could be
> using some sort of
> crazy nonlinear mapping in that range for all I
> know.  (I assume he doesn't
> though. :-) )  I would actually include a
> definition, like:
> 
> The coefficient of restitution is the ratio of the
> differences in velocities
> before and after the collision.
> 
> And include a formula too, since such a sentence can
> be confusing.  Then
> document the variables in the formula.  Also, if the
> value has some sort of
> unit -- unfortunately this coefficient doesn't --
> then document that too.
> Finally, I think the docs should refer to these
> numbers by their real names,
> like "coefficient of restitution" in this case,
> instead of cute names like
> 'bounce'.  If someone hasn't read all about what
> "coefficient of
> restitution" is in their high school physics book,
> they will probably not be
> using ODE anyway.
> 
> (If surface.bounce is indeed only some weird fudge
> factor instead of what
> I'm talking about, then forget what I said; then it
> is not only the docs
> that need work...)
> 
> But again, bounce is only an example, I am actually
> curious about such a
> description for friction, more on that in the next
> email.
> 
> 
> --Adam
> 
> 
> 
> 
> 
> _______________________________________________
> ODE mailing list
> ODE at q12.org
> http://q12.org/mailman/listinfo/ode

__________________________________________________
Do You Yahoo!?
Yahoo! GeoCities - quick and easy web site hosting, just $8.95/month.
http://geocities.yahoo.com/ps/info1