[ODE] ODE Doc & Manual ?

[Vadim Macagon]

Frankly I have little faith in a Wiki Manual working out, if the Wiki is 
unloved now what makes people think a prettier version is going to be 
better maintained? I think it's important to have a Manual that can be 
used offline, if there is a way to convert a Wiki to a PDF or CHM then I 
guess a Wiki will do.


Jean de Largentaye wrote:
> 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
>