[ODE] ODE Doc & Manual ?

[J. Perkins]

On 4/7/06, Jean de Largentaye <jlargentaye at gmail.com> wrote:
> 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. :)

I am in the process of converting the existing documentation,
including the manual, to Doxygen. You can see a bit of it at
http://opende.sf.net/docs/.

I agree with you completely about the wiki. IMHO it should be moved to
SF.net so all of the project admins have the ability to maintain it.
And it is certainly ugly and unloved. If you have some time to
contribute, I think moving the wiki to SF.net and organizing all of
the existing content would be a HUGE help.

If there is anything you need me to do (permissions, etc.) just let me know.

Jason