RE: [Playerstage-developers] bright ideas on documentation?

[Kratochvil, B. E. <kra...@ir...>]

Hello,

I'm by no means an expert on this, but I am a fan of Doxygen.  I think
with a little thought (and some time) it can answer most of the
questions you posed.

 - Crappy-looking/poorly organized manuals.  I was mostly looking at PDF
at
   the time, so this may no longer be a problem.

I believe this is more of a developer issue than a documentation tool
problem.  Some of these tools take a while to get setup and your final
document organized, which many of us don't want to spend the time to do.
Doxygen allow you to use html in the documentation, so you really don't
have many restrictions on what you put in for documentation and how it
looks.  I also think they use style sheets reasonably well, so you have
a lot of flexibility.  Player already has a pretty good organization for
the manuals, so it should really just take some work as to how to
translate that to the next program.

 - Insufficient flexibility.  These tools are great at generating API
   lists (i.e., reference manuals), but are less useful for user manuals
   (which have a very different structure).  With these tools, we would
   probably have to split the existing manual.

I agree on this one.  Most tools are great for making API references,
but are a bit lacking when it comes to making a user manual.  On the
flip side, I recently ran into a project that seems to do good job of
documenting the API and making a reference manual all with Doxygen.
Check out the reference manual at
http://cimg.sourceforge.net/reference/index.html.  It's not a huge
manual, but you can see how something similar for Player could be built.

 - Multi-media-poor.  Some drivers are quite complex, and benefit
   enormously from the inclusion of pictures and (imagine!) animations.
   The resource management for this could be tricky.

The way the last project I mentioned handled the images and other
multimedia content was just to dump them all in the subdirectory where
the documentation was built and use relative URIs in your html.  It
would be a little more complicated in terms of Player, but I think it
could be done cleanly.

One thing that may be tricky with Player is keeping all the different
types of documentation partitioned.  It would be good to have a way to
keep the client libs, server, examples, and whatever else all separated
as they currently are.  I have no idea as to how you'd do this one in
Doxygen, but I don't think it should be that bad.

Well, that's my $.02.  I'd be willing to help on this effort in a few
months.  I'm under the gun right now, but life will get better in
November (I hope).

Cheers,

bk