[ODE] ODE Documentation

[Geoff Carlton]

If doxygen is introduced, it should be in parallel, rather than dropping 
the current doc.  I like doxygen, but have found the "out of the box" 
results leave much to be desired, especially compared ODE's the current 
API document.

You just can't beat a high quality hand tailored PDF document, where 
everything is put into its own logical section.  A good document is more 
than just function definitions - each section has ideas that need to be 
conveyed first, such as the concept of what a joint is.  If I add a half 
dozen functions for offset geom, the document should have a new section 
explaining the idea, not just regenerate itself with a dozen new 
function hyperlinks on the main page.

Does anybody know where the "source format" for the current document 
is?  If it were found, I would suggest a format for the API document be 
the converted to the OpenOffice ODF format.  It is a standard format, 
there are many free cross platform editors that use it, and OpenOffice 
can natively convert to PDF (and perhaps HTML?).  Given how solid the 
ODE API is, and how few changes there have been even now since 0.5, I 
would think it would be very easy to keep it in sync.

So I would suggest three parts, at least in the short term:
 - User manual (wiki, etc)
 - API manual (single document, exported to PDF, HTML, DOC, etc)
 - doxygen interface

Geoff



Jean-Sebastien Guay wrote:
> Hello,
>
>   
>> Separate documentation into:
>> - User manual (tutorial style approach)
>> - Reference manual (api)
>>     
>
> I agree completely. The current user manual tries to be both and fails at both
> IMVHO. A user manual should consist of several short pages with a how-to style
> of writing. Then, if we need more implementation details, we can go check the
> Doxygen reference.
>
> For a good example of this, see OpenSG's documentation. There's a tutorial
> http://www.opensg.org/doc-1.6.0/TutorialIntroduction.html
> and an API reference
> http://www.opensg.org/doc-1.6.0/index.html
>
> In this case, they used Doxygen for both, but the tutorial could work as
> straight HTML or anything else. A Wiki in this sense would work well, as long
> as you keep pages short and to the point (easy to update, easy to find
> information).
>
> J-S
> --
> ______________________________________________________
> Jean-Sebastien Guay     jean-sebastien.guay at polymtl.ca
>                          http://whitestar02.webhop.org
> _______________________________________________
> ODE mailing list
> ODE at q12.org
> http://q12.org/mailman/listinfo/ode
>
>
>