[ODE] ODE Doc & Manual ?

[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