[ODE] ODE Doc & Manual ?

[Jordi]

I feel that the community using ODE is far bigger than the community 
developing it internally.
A Wiki-like manual, HOWTOs,etc. Where everybody can edit articles will get a 
big deal of care of the ODE's users. So developers can focus in other issues, 
for instance document the source.
I like the Ogre3D style with the big API on one hand and the wiki on the 
other.

--
Jordi Polo



Friday 07 April 2006 16:05、Jean de Largentaye さんは書きました:
> Hi folks,
>
> I'm fooling around with the ODE documentation, but want to recap
> what's been decided (if anything has been decided) before going ahead
> and doing stupid things :
>
> Work has started on getting Doxygen-based docs in the source (thanks
> Jason!). Where we go from here is still to be decided.
> Doxygen is great to have docs that are closely related to the code,
> like an API reference. However, if you want to modify it, you have to
> download the whole source tree through SVN, make your change, and
> commit that. Requirements: SVN installed, commit access, extra effort.
> Those are the same requirement than for the previous, snarf-based
> format, so no challenge there.
>
> I really like the format of the "previous" documentation, which mixes
> concept explanation with API doc. Some people disagree.
>
> There has been a general consensus (if not, holler) to break down the
> doc into API and Manual. The API would be doxygen-based and the Manual
> probably wiki-based. I like this idea, because it minimizes the
> obstacle in updating the manual, while keeping the API closely tied to
> the code. By Manual, I basically mean everything but the API:
> tutorials, howto's FAQ, etc..
>
> Of course I'm worried about API and Manual getting out of sync, but
> hopefully the manual will get more attention, and I believe this
> compensates.
>
> That said, the current q12-hosted wiki is underloved. (Heck, I find it
> downright ugly) Wiki technology has progressed by leaps and bounds
> since ODE's wiki was put into place, and I think we could benefit from
> that. I think it's important to have a nice facade, it attracts more
> attention, and thus more involvement.
>
> However, I don't want to setup a wiki in my corner, work on that, and
> tell people to come work on mine. It's essential to keep ODE resources
> together. So if you decide to upgrade the wiki, it should happen
> either on Russ' q12.org/ode.org or on SourceForge.
>
> Alternatively, there have been voices in favour of a php.net-like
> manual. (check the Documentation part of the php.net website if you
> don't knwo what I mean). This would mean a clean, "static" doc, but
> with the general public being able to put comments. I don't know how
> it works behind the scenes on php.net, but believe it's closer to our
> current system where a select few can modify the Official doc.
>
> Finally, we could have the Manual in doxygen format. This would lead
> to a more unified overall doc, hopefully of better quality. We'll lose
> the possibility of casual-user-contributed changes. This is similar to
> the current scheme, with the doc in the repository, and
> user-contributed comments go into the Wiki. But as I've pointed out
> before, the Wiki needs work.
>
> Wether it's better to have a wiki-based, php.net-like, or doxygen
> manual depends on the Documentor's involvement:
> - if no-one wants to put a special effort into the doc, better to go
> wiki-based and let everyone be able to make small (or larger) changes
> to the Doc.
> - if there is someone ready to take on the task of having the doc
> up-to-date, either go doxygen or php.net-like. If we go php.net, what
> framework/CMS exist out there to set it up?
>
> In anything but doxygen-based, we'll lose the possibility of alternate
> formats for the doc, like PDF.
>
> I'm personally motivated to put an effort into the doc, but I know me,
> and it won't last. Because of this, I'm more in favour of a Wiki-based
> manual.
>
> This will be a step away from Russ' manual+API, which I found of great
> quality in general. I liked this idea and would like to keep something
> of it. For example generously sprinkle the manual with links to the
> doxygen-based API. This implies having up-to-date (nightly generated?)
> doxygen API somewhere.
>
> Actions to be taken are :
> - Wherever the Manual goes. It'll need to be converted from it's
> original snarf format.
> - Setup a Wiki or php.net-like site to house the Manual, if that's the
> way it goes.
> - Comment the code for doxygen!
> - setup nightly generation of doxygen Doc.
>
> OK, now that I've said a load of crap in typical end-of-week fashion,
> what have you to say about it? In the meantime, I'll fiddle around
> with doxygen. :)
>
> John
>
> _______________________________________________
> ODE mailing list
> ODE at q12.org
> http://q12.org/mailman/listinfo/ode